Worktrees & Parallelism

The second you run more than one agent, the files start colliding — and that becomes the failure. Two agents writing the same file is the exact same headache as two engineers committing to the same lines without talking first.

The fix: a git worktree

A git worktree is a separate working directory on its own branch, sharing the same repo history. One agent's edits literally cannot touch the other's checkout.

# Create an isolated worktree on a new branch
git worktree add ../project-fix-auth fix-auth

# Two agents can now work the same repo in parallel
# Agent A works in ./project (main)
# Agent B works in ../project-fix-auth (fix-auth branch)
# Their edits cannot collide.

How the tools surface it

Claude Code gives you the same isolation three ways:

git worktree directly
a --worktree flag to open a session in its own checkout
isolation: "worktree" on a subagent, so each helper gets a fresh checkout that cleans itself up afterward

Codex builds worktree support in at the thread level — several threads hit the same repo at once and don't bump into each other.

# Claude Code subagent with its own worktree (auto-cleaned)
---
name: fix-agent
isolation: "worktree"
---

The real ceiling is you, not the tool

Worktrees take away the mechanical collision. They do not take away the human one. Your review bandwidth decides how many parallel agents you can actually run.

The orchestration tax

You can spin up eight worktrees with eight agents, but you still have to review what comes back. The tool removes the file-collision ceiling; you remain the review ceiling. Running more agents than you can review doesn't make you faster — it makes your queue deeper and your comprehension shallower.

When to reach for worktrees

You have independent tasks (fix auth bug, add export feature, update deps) — not tasks that touch the same files.
You can actually review the outputs in parallel. If you can't, run sequentially.
The task is worth the isolation overhead (each worktree is a fresh checkout to build and verify).

What this block contributes to the loop

Worktrees let the loop act in parallel without corrupting itself. Without them, a loop that spawns sub-agents to fix three issues at once would produce three conflicting patches to the same file. With them, each sub-agent works in its own branch and the loop merges what survives review.

Next: Skills — so you stop re-explaining your project to the agent every single run.