# awaywork

> A harness that runs your coding agents on your real tasks, under rules you set. An open-source CLI that pulls a developer's items from their forge and task tracker (GitHub, Asana, Linear, Jira Cloud), matches them against an ordered queue of rules, and runs the vendors' own agent CLIs (Claude Code, Codex, Cursor) on them headless with the developer's login, pacing their quota. Output is a draft PR from a new branch on GitHub or Bitbucket Cloud, a report, or a question, plan or result on the developer's own item, which can wait for their reply.

Every page is Markdown at its URL below; llms-full.txt has them all in one file.

## Start

- [Getting started](https://andreaprovenzale.github.io/awaywork/guide/getting-started.md): Install awaywork, write a config, preview the next run with plan, run one unit, then put it on a schedule.
- [How it works](https://andreaprovenzale.github.io/awaywork/guide/how-it-works.md): How a run works, from items to units, the queue of rules, the quota budget and routing, the worker's workspace, and what each deliver leaves, from a draft PR to a report, a pending review or a push onto your own PR.
- [/away in Claude Code](https://andreaprovenzale.github.io/awaywork/guide/away.md): The awaywork plugin for Claude Code, from installing it and letting /away set awaywork up in rounds of questions to the pane beside the chat with what needs you, what ran and your config, and the skill that writes your queue.
- [With an AI agent](https://andreaprovenzale.github.io/awaywork/guide/agents.md): Ask a coding agent what awaywork did and why, and let it write your awaywork queue, with the skill awaywork ships for Codex and friends, plus which commands are safe to run unattended and the machine-readable docs to read.
- [Suggested rules](https://andreaprovenzale.github.io/awaywork/guide/suggest.md): Let your coding agent read your recent sessions and PRs, with your say-so every run, and suggest awaywork queue rules, routines and AGENTS.md lines for the work you already hand off by reflex, each checked on your real items.

## Day to day

- [Plan, run, report](https://andreaprovenzale.github.io/awaywork/guide/running.md): Read the plan awaywork would run, with plan --why, --skipped and --rules, why a unit waits, run one unit, detached or narrowed to a repo or a rule, and read the morning report, its keys, report.md and stats.
- [Where results go](https://andreaprovenzale.github.io/awaywork/guide/results.md): Where a unit's results go and who sees them, from the morning report and pending reviews to draft and ready PRs, and the notify hook that runs your command after each step and each run.
- [Skills](https://andreaprovenzale.github.io/awaywork/guide/skills.md): The built-in awaywork skills, how skills are resolved, ejecting one to tweak it, and writing your own as an Agent Skills folder.

## Configure

- [The config file](https://andreaprovenzale.github.io/awaywork/guide/config/index.md): The awaywork config file: where it lives, editing it safely, what stays stable, sharing settings with extends, old runs and secrets, with links to each part of the config.
- [Queue rules](https://andreaprovenzale.github.io/awaywork/guide/config/queue-rules.md): Queue rules decide which skill runs on which item: the first match, the default queue, awaywork's own PRs, a plan's tasks, finished items, order, retrying on the next model, on_done moves and comments, and run: soon.
- [Matching items](https://andreaprovenzale.github.io/awaywork/guide/config/where.md): How a rule's where picks items, and the fields each source gives: GitHub, Asana, Linear, Jira, routines and your own.
- [Chains](https://andreaprovenzale.github.io/awaywork/guide/config/chains.md): Chains in awaywork, steps that run after a rule's skill in the same clone, covering then, review-and-fix loops, when conditions, pushing onto your own PR and keeping it in line with its base.
- [Providers and budget](https://andreaprovenzale.github.io/awaywork/guide/config/providers.md): When runs start and how much one does (windows, limits, budget), and the agents awaywork runs: their settings, which login each uses, and bringing your own CLI.
- [Sources](https://andreaprovenzale.github.io/awaywork/guide/config/sources.md): Where items come from: GitHub, Asana, Linear and Jira sources, tracker tokens, context commands, Bitbucket with Jira, and routines.
- [Custom sources](https://andreaprovenzale.github.io/awaywork/guide/config/custom-sources.md): Plug any task tracker into awaywork with a command that prints your open items as JSON, in any language, locally or on GitHub Actions.
- [Repos and branches](https://andreaprovenzale.github.io/awaywork/guide/config/repos.md): Per-repo settings and instructions, what runs in the clone, the branch names units push to, and how a PR is linked to its item.
- [MCP servers](https://andreaprovenzale.github.io/awaywork/guide/config/mcp.md): Declaring MCP servers in the config and giving them to rules and chain steps, with their secrets and tools.

## Workflows

- [Overview](https://andreaprovenzale.github.io/awaywork/guide/workflows/index.md): Where awaywork stops for you and how work goes on from your answer, covering questions on your item, drafts that continue, gates and decision cards, plans split into tasks across repos, posts that wait for your approve, threads, the files a store keeps, and proving a change with a skill of your own.
- [Questions and continue](https://andreaprovenzale.github.io/awaywork/guide/workflows/questions.md): A step that needs your answer asks on your item and goes on from your reply; work too big for one run continues on the same draft in the next.
- [Gates](https://andreaprovenzale.github.io/awaywork/guide/workflows/gates.md): Gates and judges: a change that needs a human gets a decision card on the PR, gates fail closed, and a rule's own gates.
- [Plans](https://andreaprovenzale.github.io/awaywork/guide/workflows/plans.md): A deliver: plan rule splits a feature into tasks you approve first: plan.yml, the plan comment, your answer and what makes a plan refused.
- [Tasks](https://andreaprovenzale.github.io/awaywork/guide/workflows/tasks.md): An approved plan's tasks: child items with their own branch and PR, report tasks, the feature block, tasks across repos with a contract, and waiting on a check.
- [Posts that wait and threads](https://andreaprovenzale.github.io/awaywork/guide/workflows/posts.md): A report you read before the next stage starts, and a GitHub issue as the thread when the card can't take awaywork's posts.
- [Store](https://andreaprovenzale.github.io/awaywork/guide/workflows/store.md): Big plans, contracts and screenshots live in a store outside the post and come back to the next step, where an edit is feedback.
- [Proving a change](https://andreaprovenzale.github.io/awaywork/guide/workflows/proving.md): A skill of your own shows the change does what the card asks, and gates check what it left.

## Run it

- [Where to run](https://andreaprovenzale.github.io/awaywork/guide/scheduling/index.md): Run awaywork in its windows on your machine with launchd, systemd or cron, in GitHub Actions on GitHub's runners or your own, or in a container on Coolify or any Docker host.
- [On your machine](https://andreaprovenzale.github.io/awaywork/guide/scheduling/machine.md): Run awaywork in its windows on your machine with launchd, systemd or cron, soon runs, and waking up for them.
- [In GitHub Actions](https://andreaprovenzale.github.io/awaywork/guide/scheduling/actions.md): Run awaywork in GitHub Actions on GitHub's runners or your own: the action, running one item now, reports, credentials, Codex and Cursor on a runner.
- [In a container](https://andreaprovenzale.github.io/awaywork/guide/scheduling/container.md): Run awaywork's image on Coolify, a VPS or any Docker host, and living with it there.
- [From your laptop](https://andreaprovenzale.github.io/awaywork/guide/scheduling/laptop.md): Drive a remote awaywork from your laptop, over ssh among other ways.

## Safety

- [Overview](https://andreaprovenzale.github.io/awaywork/guide/safety/index.md): What an awaywork worker can and cannot do, how pushes are guarded, how the watchdog works, and the vendor terms each provider runs under.
- [Isolation](https://andreaprovenzale.github.io/awaywork/guide/safety/isolation.md): Running setup, the agent and the checks as a worker user or in a container, what isolation: none leaves open, and how each setup closes it.
- [What awaywork publishes](https://andreaprovenzale.github.io/awaywork/guide/safety/publishes.md): Every write awaywork makes and its guard: new branches, your own PR, its own draft, PR bodies, gates, tracker writes, the store, thread issues, reports and pending reviews.

## Examples

- [A full config](https://andreaprovenzale.github.io/awaywork/examples/full-config.md): Most awaywork config keys in one file, with their defaults.
- [Morning report on your phone](https://andreaprovenzale.github.io/awaywork/examples/ntfy-report.md): A notify hook that sends the morning report to ntfy, or Slack.
- [A Notion page per plan](https://andreaprovenzale.github.io/awaywork/examples/notion-plans.md): A notify hook that writes each plan step's report to a Notion page, and why a hook beats an MCP server here.
- [Slack when a review is ready](https://andreaprovenzale.github.io/awaywork/examples/slack-reviews.md): A notify hook that posts to a Slack incoming webhook once per finished review step.
- [Acting on a skill's output](https://andreaprovenzale.github.io/awaywork/examples/skill-output.md): A notify hook that reads a file the skill wrote in .away/out/ and labels the issue, treating the file as untrusted.
- [Chores](https://andreaprovenzale.github.io/awaywork/examples/chores.md): A custom source that hands out work with no tracker item, one item per chore and repo.
- [Sentry errors](https://andreaprovenzale.github.io/awaywork/examples/sentry.md): A custom source for your unresolved Sentry issues with their latest stack trace, and a rule for fix.
- [Markdown files as threads](https://andreaprovenzale.github.io/awaywork/examples/markdown-threads.md): A thread host script keeping one Markdown file per card, in a folder only you write to.

## Reference

- [CLI](https://andreaprovenzale.github.io/awaywork/reference/cli.md): Every awaywork command and option, from its --help.
- [Config](https://andreaprovenzale.github.io/awaywork/reference/config.md): Every config key with its type, default and meaning, from the JSON Schema.

## Extend

- [Adding a provider](https://andreaprovenzale.github.io/awaywork/extend/providers.md): How to add a coding-agent provider to awaywork, with the research it needs first, the Provider contract, the registry line, tests against a fake binary, and a burn test.
- [Adding a source](https://andreaprovenzale.github.io/awaywork/extend/sources.md): How to add a work source such as a task tracker to awaywork, with the Source contract, fields for queue rules, prefetched context, discovery and contract tests.

## Research

- [Providers](https://andreaprovenzale.github.io/awaywork/providers.md): Research on which coding subscriptions can run headless and remotely, how their quota can be read, and what their terms allow, with claims tagged by evidence.
- [Sources](https://andreaprovenzale.github.io/awaywork/sources.md): Research on which task trackers a script can read headless, their tokens and limits, and why awaywork uses thin adapters instead of MCP.