AWO – Run Claude and Codex in isolated Git worktrees

AWO is a new Go CLI tool that runs Claude Code and Codex in isolated git worktrees, preventing agent edits from directly modifying a developer's working tree. The tool executes agents in single, writer-reviewer, or competitive modes, runs user-configured verification commands, and produces structured artifact bundles for human review before any changes are committed or merged.

AWO is a local Go CLI that coordinates Claude Code and Codex across isolated git worktrees, runs deterministic verification commands against the result, and produces a structured artifact bundle run.json , proof-pack.md , diff.patch , agent stdout/stderr that a human reviews before merging. AWO does not commit, push, merge, or open pull requests on your behalf. A small, opinionated wrapper around two existing CLI tools — claude and codex — that: - Carves out an isolated git worktree per agent so agent edits never touch your working tree directly. - Runs the agents you choose against the same task, in one of three modes single , writer-reviewer , competitive . - Runs the verification commands you configure e.g. go test ./... inside the worktree, and treats the exit code as the only trusted signal of success. - Writes a deterministic artifact bundle under .awo/runs/<run-id / so the run is auditable after the fact. - Hands the result back to you as a candidate change to review, commit, push, and PR — manually. Letting an agent edit your live working tree is high-blast-radius: mid-run failures leave you with a half-applied change, parallel processes your editor, your dev server see partial state, and there is no clean "undo" if the agent goes off the rails. git worktree lets each agent run in its own checkout of your repo on its own branch, sharing the same .git directory. AWO uses that to: - Run multiple agents in parallel competitive mode without them stepping on each other. - Bound the blast radius: AWO will only ever delete paths under .awo/worktrees/ , never your real source tree. - Capture an exact diff per agent for review. Claude Code and Codex have meaningfully different strengths, prompt ergonomics, and failure modes. Forcing one to ape the other loses information — you want the real output of each. Single mode lets you pick the better tool for the task at hand. Writer-reviewer mode uses one as the writer and the other as the reviewer, which surfaces blind spots that a same-model review would not catch. Competitive mode runs both on the same task and ranks them with a deterministic, explainable scoring function — never with an LLM judge. The two backends are wired through small adapter layers so adding a third or swapping CLI versions is a config change, not a code change. Requires Go 1.22+. install into $GOBIN go install github.com/awo-dev/awo/cmd/awo@latest or build a local binary git clone https://github.com/ystepanoff/awo.git cd awo go build ./cmd/awo The awo binary is the only thing AWO ships — no daemon, no service, no remote dependencies. git on $PATH - Go 1.22+ only for building from source - The Claude CLI claude installed and authenticated: https://docs.anthropic.com/en/docs/claude-code https://docs.anthropic.com/en/docs/claude-code - The Codex CLI codex installed and authenticated: https://github.com/openai/codex https://github.com/openai/codex awo doctor checks all four and prints what's missing or unauthenticated. Inside your project's git repo: awo init scaffold .awo/, awo.config.json, CLAUDE.md, AGENTS.md awo doctor confirm git/go/claude/codex are reachable awo run "add tests for calculator" \ --mode single \ --agent claude \ --verify "go test ./..." Want a safe sandbox before pointing AWO at your real code? awo examples create-fixture materializes a tiny self-contained Go module under .awo/fixtures/sample-go-app/ its own git repo so you can dogfood every mode without risk. One agent does the work end-to-end inside a writer worktree. Verification runs in the same worktree. awo run "fix the off-by-one in pagination" \ --mode single \ --agent claude \ --verify "go test ./..." awo run "fix the off-by-one in pagination" \ --mode single \ --agent codex \ --verify "go test ./..." Use this when you've already decided which agent is best suited to the task. A primary agent writes the change in a writer worktree; a different agent reviews the writer's diff in a separate read-only worktree carved from the same base. The reviewer's findings are surfaced in the proof pack, but the reviewer cannot modify the writer's worktree — any files it touches in its own worktree become a warning, not a patch. awo run "fix checkout validation" \ --mode writer-reviewer \ --primary claude \ --reviewer codex \ --verify "go test ./..." Use this when you want a different model's eyes on the change before you spend your own attention on it. Two agents attempt the same task in parallel in independent worktrees. AWO runs verification against each, scores them with a deterministic function verification status, diff size, test files added, protected paths touched , and surfaces the comparison. awo run "migrate date utility usage" \ --mode competitive \ --competitors claude,codex \ --verify "go test ./..." There is no LLM judge . The scoring is intentionally explainable — the proof pack lists the inputs to every score so you can disagree with the ranking on the spot. AWO's safety stance is captured in three rules: Verification command exit codes are the only trusted signal of success. Agent self-reports "I ran the tests and they passed" are persisted as advisory metadata only. AWO never mutates state outside its sandbox. Worktree deletions are constrained to paths under .awo/worktrees/ . Branches outside config.branchPrefix default awo are never touched. The outer repo's HEAD and working tree are never modified by AWO. Human review is always required. AWO has no merge button. The final step of every run is a recommendation to a human, who is the only thing that turns AWO output into a real PR. Additional hard rules implemented in code: - Protected paths default: auth/ , payments/ , migrations/ , infra/ , .github/workflows/ , /.env , / secret , / credential , / permission escalate the recommendation to needs human attention whenever they are touched. - Patches that exceed safety.maxChangedFiles default 50 escalate to too large for auto review . - Reviewer-side worktree edits in writer-reviewer mode are detected and surfaced as warnings, never applied. - Agents are not allowed to inspect each other's worktrees. See docs/safety.md /ystepanoff/awo/blob/main/docs/safety.md for the full list. - It does not auto-merge. - It does not auto-commit. - It does not push to remotes. - It does not open pull requests. awo pr prepare writes a pr-description.md you can paste; it does not call gh . - It does not delete files outside .awo/worktrees/ . - It does not guarantee correctness. Agents make mistakes; tests miss things; the recommendation is a heuristic. - It is not a replacement for human code review. Every run writes a directory under .awo/runs/<run-id / : .awo/runs/20260525-094200-abc123/ ├── run.json canonical machine-readable record RunReport ├── proof-pack.md long-form human report ├── summary.md short-form human summary ├── comparison.md competitive mode only ├── pr-description.md written by awo pr prepare not by run ├── diff.patch the diff produced by the selected candidate ├── agents/ │ └── <agent -<role / per-agent stdout, stderr, prompt, command └── verify/ └── 000/ per-verification-command stdout, stderr, exit Inspecting after a run: ls .awo/runs/$ ls -t .awo/runs | head -n 1 / cat .awo/runs/<run-id /proof-pack.md git -C <worktree-path diff awo worktrees list shows the worktrees AWO is tracking; awo worktrees cleanup --run-id <id removes them when you no longer need them. awo init writes awo.config.json with sensible defaults. The full schema and recommended overrides are in docs/configuration.md /ystepanoff/awo/blob/main/docs/configuration.md . Highlights: | Field | Default | What it controls | |---|---|---| branchPrefix | awo | All AWO branches start with this prefix; nothing else is touched. | worktreeBaseDir | .awo/worktrees | Where worktrees live; deletions are bounded to this path. | artifactDir | .awo/runs | Where run artifacts are written. | defaultVerifyCommands | | Commands run when --verify is not passed. | agents.claude.command / writerArgs / reviewerArgs | claude / -p --permission-mode acceptEdits / -p --permission-mode plan | Per-role argv. AWO runs every agent non-interactively; if the CLI hits an approval prompt the run fails closed with permission required . | agents.codex.command / writerArgs / reviewerArgs | codex / exec --sandbox workspace-write --ask-for-approval never / exec --sandbox read-only --ask-for-approval never | Same. AWO refuses dangerous bypasses bypassPermissions , danger-full-access , etc. . | safety.maxChangedFiles | 50 | Patches above this escalate to too large for auto review . | safety.protectedPaths | 9 globs | Hits escalate to needs human attention . | safety.requireConfirmationForProtectedPaths | true | Reserved for future interactive prompts. | Run awo config print to see the effective config file values layered on top of defaults . Short term: - More verification adapters beyond shell commands lint, typecheck . - Pluggable scoring weights for competitive mode. - A "rerun" subcommand that resumes a failed run from artifacts. - Iteration support safety.maxIterations is currently fixed at 1 . Longer term: - Adapters for additional agent backends Gemini CLI, etc. . - A small TUI for inspecting runs in place. - A signing/attestation pass over run.json so artifacts can be trusted across machines. Explicitly out of scope: - LLM-as-judge scoring. - Auto-commit, auto-push, auto-merge — ever. - Anything that mutates state outside the configured AWO sandbox. — package layout and how a run flows through AWO. docs/architecture.md — the full safety model and the invariants tests enforce. docs/safety.md — the prompt contract AWO uses with Claude and Codex. docs/prompts.md — worked examples for every mode using the bundled fixture. docs/examples.md — full docs/configuration.md awo.config.json reference.— how to build, test, and contribute. docs/development.md See LICENSE /ystepanoff/awo/blob/main/LICENSE .