{"slug": "awo-run-claude-and-codex-in-isolated-git-worktrees", "title": "AWO – Run Claude and Codex in isolated Git worktrees", "summary": "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.", "body_md": "AWO is a local Go CLI that coordinates Claude Code and Codex across isolated\ngit worktrees, runs deterministic verification commands against the result,\nand produces a structured artifact bundle (`run.json`\n\n, `proof-pack.md`\n\n,\n`diff.patch`\n\n, agent stdout/stderr) that a human reviews before merging.\n\nAWO does not commit, push, merge, or open pull requests on your behalf.\n\nA small, opinionated wrapper around two existing CLI tools — `claude`\n\nand\n`codex`\n\n— that:\n\n- Carves out an isolated git worktree per agent so agent edits never touch your working tree directly.\n- Runs the agents you choose against the same task, in one of three modes\n(\n`single`\n\n,`writer-reviewer`\n\n,`competitive`\n\n). - Runs the verification commands\n*you*configure (e.g.`go test ./...`\n\n) inside the worktree, and treats the**exit code as the only trusted signal** of success. - Writes a deterministic artifact bundle under\n`.awo/runs/<run-id>/`\n\nso the run is auditable after the fact. - Hands the result back to you as a candidate change to review, commit, push, and PR — manually.\n\nLetting 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.\n\n`git worktree`\n\nlets each agent run in its own checkout of your repo on\nits own branch, sharing the same `.git`\n\ndirectory. AWO uses that to:\n\n- Run multiple agents in parallel (competitive mode) without them stepping on each other.\n- Bound the blast radius: AWO will only ever delete paths under\n`.awo/worktrees/`\n\n, never your real source tree. - Capture an exact diff per agent for review.\n\nClaude Code and Codex have meaningfully different strengths, prompt\nergonomics, and failure modes. Forcing one to ape the other loses\ninformation — you want the *real* output of each.\n\n**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.\n\nThe two backends are wired through small adapter layers so adding a third (or swapping CLI versions) is a config change, not a code change.\n\nRequires Go 1.22+.\n\n```\n# install into $GOBIN\ngo install github.com/awo-dev/awo/cmd/awo@latest\n\n# or build a local binary\ngit clone https://github.com/ystepanoff/awo.git\ncd awo\ngo build ./cmd/awo\n```\n\nThe `awo`\n\nbinary is the only thing AWO ships — no daemon, no service,\nno remote dependencies.\n\n`git`\n\non`$PATH`\n\n- Go 1.22+ (only for building from source)\n- The Claude CLI (\n`claude`\n\n) installed and authenticated:[https://docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code) - The Codex CLI (\n`codex`\n\n) installed and authenticated:[https://github.com/openai/codex](https://github.com/openai/codex)\n\n`awo doctor`\n\nchecks all four and prints what's missing or\nunauthenticated.\n\n```\n# Inside your project's git repo:\nawo init                                  # scaffold .awo/, awo.config.json, CLAUDE.md, AGENTS.md\nawo doctor                                # confirm git/go/claude/codex are reachable\nawo run \"add tests for calculator\" \\\n    --mode single \\\n    --agent claude \\\n    --verify \"go test ./...\"\n```\n\nWant a safe sandbox before pointing AWO at your real code?\n`awo examples create-fixture`\n\nmaterializes a tiny self-contained Go\nmodule under `.awo/fixtures/sample-go-app/`\n\n(its own git repo) so you\ncan dogfood every mode without risk.\n\nOne agent does the work end-to-end inside a writer worktree. Verification runs in the same worktree.\n\n```\nawo run \"fix the off-by-one in pagination\" \\\n    --mode single \\\n    --agent claude \\\n    --verify \"go test ./...\"\n\nawo run \"fix the off-by-one in pagination\" \\\n    --mode single \\\n    --agent codex \\\n    --verify \"go test ./...\"\n```\n\nUse this when you've already decided which agent is best suited to the task.\n\nA primary agent writes the change in a writer worktree; a different\nagent reviews the writer's diff in a separate read-only worktree\ncarved from the same base. The reviewer's findings are surfaced in the\nproof pack, but **the reviewer cannot modify the writer's worktree** —\nany files it touches in its own worktree become a warning, not a\npatch.\n\n```\nawo run \"fix checkout validation\" \\\n    --mode writer-reviewer \\\n    --primary claude \\\n    --reviewer codex \\\n    --verify \"go test ./...\"\n```\n\nUse this when you want a different model's eyes on the change before you spend your own attention on it.\n\nTwo 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.\n\n```\nawo run \"migrate date utility usage\" \\\n    --mode competitive \\\n    --competitors claude,codex \\\n    --verify \"go test ./...\"\n```\n\nThere is **no LLM judge**. The scoring is intentionally\nexplainable — the proof pack lists the inputs to every score so you can\ndisagree with the ranking on the spot.\n\nAWO's safety stance is captured in three rules:\n\n**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/`\n\n. Branches outside`config.branchPrefix`\n\n(default`awo`\n\n) are never touched. The outer repo's`HEAD`\n\nand 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.\n\nAdditional hard rules implemented in code:\n\n- Protected paths (default:\n`auth/**`\n\n,`payments/**`\n\n,`migrations/**`\n\n,`infra/**`\n\n,`.github/workflows/**`\n\n,`**/.env*`\n\n,`**/*secret*`\n\n,`**/*credential*`\n\n,`**/*permission*`\n\n) escalate the recommendation to`needs_human_attention`\n\nwhenever they are touched. - Patches that exceed\n`safety.maxChangedFiles`\n\n(default 50) escalate to`too_large_for_auto_review`\n\n. - Reviewer-side worktree edits in writer-reviewer mode are detected and surfaced as warnings, never applied.\n- Agents are not allowed to inspect each other's worktrees.\n\nSee [ docs/safety.md](/ystepanoff/awo/blob/main/docs/safety.md) for the full list.\n\n- It does\n**not** auto-merge. - It does\n**not** auto-commit. - It does\n**not** push to remotes. - It does\n**not** open pull requests. (`awo pr prepare`\n\nwrites a`pr-description.md`\n\nyou can paste; it does not call`gh`\n\n.) - It does\n**not** delete files outside`.awo/worktrees/`\n\n. - It does\n**not** guarantee correctness. Agents make mistakes; tests miss things; the recommendation is a heuristic. - It is\n**not** a replacement for human code review.\n\nEvery run writes a directory under `.awo/runs/<run-id>/`\n\n:\n\n```\n.awo/runs/20260525-094200-abc123/\n├── run.json            # canonical machine-readable record (RunReport)\n├── proof-pack.md       # long-form human report\n├── summary.md          # short-form human summary\n├── comparison.md       # competitive mode only\n├── pr-description.md   # written by `awo pr prepare` (not by run)\n├── diff.patch          # the diff produced by the selected candidate\n├── agents/\n│   └── <agent>-<role>/ # per-agent stdout, stderr, prompt, command\n└── verify/\n    └── 000/            # per-verification-command stdout, stderr, exit\n```\n\nInspecting after a run:\n\n```\nls .awo/runs/$(ls -t .awo/runs | head -n 1)/\ncat .awo/runs/<run-id>/proof-pack.md\ngit -C <worktree-path> diff\n```\n\n`awo worktrees list`\n\nshows the worktrees AWO is tracking; `awo worktrees cleanup --run-id <id>`\n\nremoves them when you no longer need\nthem.\n\n`awo init`\n\nwrites `awo.config.json`\n\nwith sensible defaults. The full\nschema and recommended overrides are in\n[ docs/configuration.md](/ystepanoff/awo/blob/main/docs/configuration.md). Highlights:\n\n| Field | Default | What it controls |\n|---|---|---|\n`branchPrefix` |\n`awo` |\nAll AWO branches start with this prefix; nothing else is touched. |\n`worktreeBaseDir` |\n`.awo/worktrees` |\nWhere worktrees live; deletions are bounded to this path. |\n`artifactDir` |\n`.awo/runs` |\nWhere run artifacts are written. |\n`defaultVerifyCommands` |\n`[]` |\nCommands run when `--verify` is not passed. |\n`agents.claude.command` / `writerArgs` / `reviewerArgs` |\n`claude` / `-p --permission-mode acceptEdits` / `-p --permission-mode plan` |\nPer-role argv. AWO runs every agent non-interactively; if the CLI hits an approval prompt the run fails closed with `permission_required` . |\n`agents.codex.command` / `writerArgs` / `reviewerArgs` |\n`codex` / `exec --sandbox workspace-write --ask-for-approval never` / `exec --sandbox read-only --ask-for-approval never` |\nSame. AWO refuses dangerous bypasses (`bypassPermissions` , `danger-full-access` , etc.). |\n`safety.maxChangedFiles` |\n`50` |\nPatches above this escalate to `too_large_for_auto_review` . |\n`safety.protectedPaths` |\n(9 globs) | Hits escalate to `needs_human_attention` . |\n`safety.requireConfirmationForProtectedPaths` |\n`true` |\nReserved for future interactive prompts. |\n\nRun `awo config print`\n\nto see the effective config (file values layered\non top of defaults).\n\nShort term:\n\n- More verification adapters beyond shell commands (lint, typecheck).\n- Pluggable scoring weights for competitive mode.\n- A \"rerun\" subcommand that resumes a failed run from artifacts.\n- Iteration support (\n`safety.maxIterations`\n\nis currently fixed at 1).\n\nLonger term:\n\n- Adapters for additional agent backends (Gemini CLI, etc.).\n- A small TUI for inspecting runs in place.\n- A signing/attestation pass over\n`run.json`\n\nso artifacts can be trusted across machines.\n\nExplicitly out of scope:\n\n- LLM-as-judge scoring.\n- Auto-commit, auto-push, auto-merge — ever.\n- Anything that mutates state outside the configured AWO sandbox.\n\n— package layout and how a run flows through AWO.`docs/architecture.md`\n\n— the full safety model and the invariants tests enforce.`docs/safety.md`\n\n— the prompt contract AWO uses with Claude and Codex.`docs/prompts.md`\n\n— worked examples for every mode using the bundled fixture.`docs/examples.md`\n\n— full`docs/configuration.md`\n\n`awo.config.json`\n\nreference.— how to build, test, and contribute.`docs/development.md`\n\nSee [ LICENSE](/ystepanoff/awo/blob/main/LICENSE).", "url": "https://wpnews.pro/news/awo-run-claude-and-codex-in-isolated-git-worktrees", "canonical_source": "https://github.com/ystepanoff/awo", "published_at": "2026-05-25 19:46:25+00:00", "updated_at": "2026-05-25 20:08:16.819725+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "ai-infrastructure", "mlops", "ai-products"], "entities": ["AWO", "Claude Code", "Codex", "Claude", "Go"], "alternates": {"html": "https://wpnews.pro/news/awo-run-claude-and-codex-in-isolated-git-worktrees", "markdown": "https://wpnews.pro/news/awo-run-claude-and-codex-in-isolated-git-worktrees.md", "text": "https://wpnews.pro/news/awo-run-claude-and-codex-in-isolated-git-worktrees.txt", "jsonld": "https://wpnews.pro/news/awo-run-claude-and-codex-in-isolated-git-worktrees.jsonld"}}