Getting started

Requirements

• Node 22 or later, and git.
• Where your code lives, and awaywork pushes branches and opens draft PRs:
  • GitHub: gh logged in.
  • Bitbucket Cloud: twg logged in and an SSH key, see Bitbucket and Jira.
• At least one agent CLI, logged in with your subscription:
  • Claude Code: logged in, or CLAUDE_CODE_OAUTH_TOKEN from claude setup-token.
  • Codex: codex login.
  • Cursor: its agent CLI and a CURSOR_API_KEY, even on your machine (why).
  • Any other, opencode, Amp and friends: a command that runs it on a prompt file (Bring your own CLI).
• Where your tasks live, one source or more:
  • GitHub: your issues, your PRs and those awaiting your review. gh is enough.
  • Asana, Linear or Jira Cloud: a personal access token, a personal API key or an Atlassian API token (which).
  • Anything else, an internal board, Sentry errors, a list of chores: a command, in any language, that prints your items as JSON (Custom sources).
  • No tracker at all: routines make items from the clock.

Install

npm install -g awaywork
awaywork --help

Configure

awaywork init

init opens Claude Code on /away set up awaywork, and the /away skill does the setup with you in a few rounds of questions. No awaywork plugin in Claude Code yet? It offers to install it first:

$ awaywork init
◇  Install the awaywork plugin for Claude Code? It runs claude plugin marketplace add AndreaProvenzale/awaywork, then
│  claude plugin install awaywork@awaywork
│  Yes
✔ Successfully added marketplace: awaywork (declared in user settings)
✔ Successfully installed plugin: awaywork@awaywork (scope: user)
│
●  Opening Claude Code on /away set up awaywork; /exit comes back here

Say no and that one session loads the plugin from the npm package instead (--plugin-dir), nothing installed. The setup in full, and the pane /away opens once there's a config, are in /away in Claude Code. Run init again with a config there and /away tells you where it stands and what you could change.

No Claude Code? init says what to do instead:

• Codex gets the same plugin: see Codex and friends.
• Any agent that loads skills can take them from the package.
• awaywork init --yes asks nothing and writes the detected defaults, for a container or CI.

Or write a minimal config by hand:

providers: [claude]
repos:
  acme/*:
sources:
  github: {}
queue:
  - skill: fix
    where: { type: pr, mine: true, checks: failing }

With no queue, nothing runs. GitHub issues need a rule of their own, e.g. implement for issues labelled awaywork (see Configuration). awaywork reads the issues assigned to you, so assign yourself too: the label alone plans nothing, unless a search reads it.

Check it:

awaywork doctor   # the config, binaries, credentials, quota, sources

Preview the next run

awaywork plan

plan reads your sources and each provider's quota and shows what a run would do, without running an agent. In a terminal it opens at once and shows each step as it loads:

☾ >_ awaywork  You're away, your agents work

⠸ Planning the next run
  ✔ github        5 items
  ✔ tracker       2 items
  ✔ linking PRs   2/2
  ⠸ claude quota

q quit

What the screen shows once it has loaded, and plan --why, --skipped and --rules, are in Plan, run, report.

Run one unit

awaywork run --dry-run         # clone, context and prompt, no agent
awaywork run --unit api#1      # one real unit
awaywork report                # browse the last run; piped, its morning report

run's options, --detach and the run directory are in Plan, run, report.

On a schedule

awaywork schedule install      # asks where; this machine is launchd, systemd or cron

The job keeps awaywork watch running, which starts a run when a window opens and stops it when the window ends (01:00 to 07:00 by default). For GitHub Actions instead, pick it when asked or pass --with github-actions: see Scheduling.