Your code is durable. The context isn't.
When a session ends, what it knew goes with it: what was tried, what was decided, what comes next. aw keeps that record in a git repository of its own, with your code repositories checked out inside it. Clone it anywhere, and the next session starts where the last one stopped.
brew install aw-tools/tap/aw-cli
aw sync workspace myproject repo web fetched layer workspace fetched repo api fetched verify 2 repo(s), 0 skipped, 0 failed, 0 skill(s) linked, 0 shadowed aw status workspace myproject working tree workspace clean api clean web clean ahead/behind workspace ahead 0, behind 0 (fetched 0s ago) api ahead 0, behind 2 (fetched 0s ago) web ahead 0, behind 0 (fetched 0s ago) aw fast-forward workspace myproject repo web up to date repo api advanced 2263290..9112a87 (2 commit(s)) verify 1 advanced, 1 up to date, 0 skipped, 0 failed # the agent works, then rewrites context/STATE.md git commit -am "record: api pagination planned" [trunk e19dee2] record: api pagination planned 1 file changed, 1 insertion(+), 1 deletion(-) git push 85e841f..e19dee2 trunk -> trunk
The problem
- 01
A session ends when its context fills, the terminal closes or you change machine.
- 02
What it knew about the work is gone: the decisions, the rejected attempts, the next step.
- 03
Your code repositories cannot hold it. Commits record changes to the code, not the work around them. And work often spans several repositories.
- 04
So the next session rebuilds it from scrollback and guesswork.
How it works
A workspace is an outer git repository. Your code repositories sit inside it as members, which it never commits. It commits only its own record, and the record travels with it.
This machine
myproject.workspace/the workspace, a git repository
context/the record, committed
- STATE.md
- DECISIONS.md
- FINDINGS.md
- NOTES.md
- engagements/
api/member, never committed
web/member, never committed
Any other machine
myproject.workspace/cloned, then aw bootstrap
context/the same record
- STATE.md
- DECISIONS.md
- FINDINGS.md
- NOTES.md
- engagements/
api/cloned by bootstrap
web/cloned by bootstrap
What the record holds
A directory named context/ holds five kinds of record.
STATE.mdThe state fileWhat is live, what is next, what is blocked. Every session reads it first.
DECISIONS.mdThe decision registerEach decision with a number and a reason. Entries are added and never changed.
FINDINGS.mdThe findings fileVerified facts about the environment.
NOTES.mdThe notes fileFriction and observations not yet routed anywhere.
engagements/One directory per engagementA piece of work with a start and an end: its plan, and a ledger of what ran and what it showed.
Beside the record, AGENTS.md holds your agents' instructions, and each member's skills are linked where Claude Code and Codex both read them.
The tool
Set up
aw init- Creates a workspace from a template.
aw bootstrap- Clones the members on a new machine and links their skills.
Day to day
aw status- Reports each repository's position and whether its working tree is clean.
aw sync- Fetches the workspace and every member at once.
aw fast-forward- Brings the members that are safe to move up to date.
The contract
A written contract of numbered clauses defines the layout and names no tool. A conformance suite of example workspaces proves that a tool follows it, so other tools can read the same record.
Get started
aw needs git, garden 2.6 or later, and dprint to keep work files tidy. Homebrew installs garden with aw.
Install the tool.
brew install aw-tools/tap/aw-cliCreate a workspace and go into it.
aw init myproject.workspace cd myproject.workspaceClone each repository you work on, then adopt it.
git clone git@github.com:you/myrepo.git aw adopt myrepoBootstrap.
aw bootstrap
If something fails, aw doctor says what is missing. Chapter 3 covers other ways to install and the first session.