Configuration

One YAML file, ~/.config/awaywork/config.yml by default; --config <path> or AWAYWORK_CONFIG point elsewhere. This page goes by example. Every key, with its type and default, is in the reference.

Where to find what:

• Editing safely: validate, preview.
• Stability: what stays valid across releases.
• A full example: most keys in one file.
• A base config: share settings with extends.
• Windows, limits and budget: when runs start, how much one does.
• Providers: agents, their settings and logins, your own CLI.
• Sources: where items come from, Bitbucket with Jira, routines.
• Branch names: what a unit pushes to.
• Linking PRs: how a PR is tied to an item.
• Repos and instructions: per-repo commands, and everything that runs in a clone.
• Queue rules: which skill runs on which item.
• Matching items: where, and each source's fields.
• Notify: your command after each step and each run.
• MCP servers: servers a rule gives its units.
• Isolation: a worker user or a container.
• Old runs and Secrets.

Gates, plans, threads and the store are in Workflows; multi-step rules in Chains.

Editing safely

awaywork doctor         # validate, including skill names
awaywork plan           # see what the change does to the next run

Or let your coding agent edit the queue, checked on your real items first: With an AI agent.

For autocompletion in editors with the YAML language server, start the file with:

# yaml-language-server: $schema=https://andreaprovenzale.github.io/awaywork/config.schema.json

awaywork config schema prints the same JSON Schema for the installed version.

Stability

From 0.1.0-rc.1, a config valid on one minor release stays valid on the next. Keys marked experimental may change in a minor release, with a note in the release notes: so far only forge.github.host.

A base config

Several configs, one per role, tend to repeat windows, budget, sources and repos. Put those in a base and have each role file extends it:

# team/base.yml
windows: [{ start: "01:00", end: "07:00" }]
limits: { unit_minutes: 45 }
providers: [claude]
repos: { acme/api: }
sources: { github: {} }
instructions: [notes/team.md]

# roles/developer.yml
extends: ../team/base.yml
limits: { units: 6, units_per_repo: 3 }
queue:
  - skill: fix
    source: github
    where: { type: pr, mine: true, checks: failing }

Maps merge key by key, the role winning: limits above gets all three keys. A list replaces the base's outright, queue and windows included, since rule order matters. An error names the file it comes from:

$ awaywork doctor --config roles/developer.yml
✖  team/base.yml: windows[0].end: expected a time like "01:00"

Details:

• extends is relative to the role file. One level only, local only: a base with its own extends, or a URL, is an error.
• There's no unsetting what the base sets: null is just an invalid value.
• Relative paths resolve against the file they're written in (notes/team.md is team/notes/team.md). So does the folder a custom source's command, a context command or a custom provider's probe runs in, and claude: { settings }. A custom source's write and setup run in the folder of the file that sets its command.
• Skills stay next to the file you pass to --config.
• An error inside a list the role sets names the role; a key only the base sets names the base.

Old runs

Run dirs keep plans, logs, context and reports, and a replay's clone, easily 100 MB. keep_runs (a span, 30d by default) says how long:

keep_runs: 14d

Each awaywork run prunes once it holds the run lock (not on --dry-run), going by run id; watch does at start and daily, logging it. Runs in progress and those holding an item's latest report stay. A removal prints Removed 3 runs older than 30d, 124.8 MB freed; a failure is a warning:. report --list, stats and replay see only kept runs.

Secrets

The config holds env var names only. Values come from the environment or ~/.config/awaywork/env, the environment winning. awaywork secret ASANA_TOKEN saves one there off your shell history, at a hidden prompt or from a pipe (pbpaste | awaywork secret ASANA_TOKEN), replacing an existing line.

Variable	Used by
CLAUDE_CODE_OAUTH_TOKEN	Claude without the local login (claude setup-token); wins over config_dir
ASANA_TOKEN, LINEAR_API_KEY, JIRA_API_TOKEN (or your token_env)	Asana, Linear, Jira
GH_TOKEN	GitHub in Actions; locally gh's login or forge.github.user's
A custom source's secrets	Its command and write
context.secrets, notify.secrets, repos.<repo>.secrets	That context command, the notify command, that repo's setup
mcp.<name>.secrets	That server, for units whose rule names it