One Git worktree per agent: the pattern behind parallel AI coding
Every serious parallel-agent tool uses the same trick: git worktree gives each agent its own directory and branch off one repository. How the pattern works, where it breaks, and what to watch.
Running one Git worktree per agent gives each session its own working directory and branch while sharing a single object store. It is the pattern under Conductor, Superset, Claude Squad, Aura Crew and most of the tools in the category, and the reason is simple: two agents cannot share one checkout without overwriting each other's files.
The mechanics
A worktree is a second checkout of the same repository, created with one command:
git worktree add ../repo-agent-1 -b agent/parse-config
git worktree add ../repo-agent-2 -b agent/retry-logicBoth directories point at the same .git objects, so the disk cost is the working files rather than the history. Each has its own branch, its own index and its own dirty state. An agent in one cannot see the uncommitted work in the other, which is exactly what you want.
What it buys
- No file-level interference: two agents can run
cargo buildat once without fighting over target directories, given separate target paths. - Clean isolation of failure: a session that goes wrong is one
git worktree removeaway from gone. - Ordinary merges: each branch merges the way any branch does, so nothing about the review path changes.
Where it breaks
| Problem | Why it happens | Fix |
|---|---|---|
| Shared build cache thrash | Two worktrees writing one CARGO_TARGET_DIR or node_modules | Give each worktree its own; never share a target directory |
| Disk fills up | Every worktree is a full checkout of the working files | Remove worktrees on completion, and prune weekly |
| Semantic conflicts | Isolation is per file, not per meaning | Symbol-level collision detection |
| Untracked files stay behind | .env and local config do not follow a new worktree | Copy or symlink them at creation time |
The third row is the one that costs the most. Worktrees isolate files. They do nothing about two agents changing the same function in two branches, which merges cleanly and breaks at runtime.
How many is too many
The limit is rarely Git. It is the machine: each agent runs a build, a test suite and a language server. Four concurrent agents on a laptop is usually the point where everything gets slower. On a server, the limit moves up until the model provider's rate limit becomes the constraint.
Cleaning up
git worktree list # what exists
git worktree remove ../repo-agent-1
git worktree prune # drop stale metadataAura creates and removes worktrees per crew task, and keeps the branch after removal so the work is recoverable. See running several agents in parallel for the scheduling side, and Aura compared with Claude Squad for a terminal-only take on the same pattern.
What is a Git worktree?
A second working directory attached to the same repository. It has its own checked-out branch and its own files, but shares the object store and history, so it costs a checkout rather than a clone and every commit is immediately visible to the others.
Why does each AI agent need its own worktree?
Because two agents in one directory overwrite each other’s edits and each other’s build output, and neither can tell that it happened. A worktree per agent gives each one a private tree and branch, so concurrent work merges through Git instead of racing on the filesystem.
How do you create a Git worktree for a coding agent?
git worktree add ../feature-x -b feature-x creates a directory with a new branch checked out. Point the agent at that directory as its working root. When the branch is merged, git worktree remove tears the directory down without touching the repository.
Is git worktree better than cloning the repo for each agent?
Usually. A worktree shares history and objects, so it is faster to create and cheap on disk, and commits made in one are instantly available in the others. A clone is only preferable when you want genuinely separate history, which parallel agents on one project do not.
What are the downsides of a worktree per agent?
Each tree needs its own dependency install and build cache, which is the real cost on large projects. Tooling that assumes one checkout per repository can get confused, and it is easy to accumulate stale worktrees for branches that were merged weeks ago.
Aura Crew vs Claude Code Loops: the autonomous work-loop, compared
Claude Code defines four loop types — turn-based, goal, time, and proactive. Aura Crew is the same idea productized: a dependency-ordered work-loop with proof, collision-safety, and any agent. Full comparison.
Autonomous coding agent loops, explained: turn-based, goal, time, and proactive
A coding agent loop is an agent repeating cycles of work until a stop condition is met. The four types explained — turn-based, goal-based, time-based, proactive — with when to use each and how to keep quality high.
How to run multiple coding agents in parallel without merge conflicts
Running several AI coding agents at once collides on shared files. The fix: a worktree per agent, a live team radar, and soft-to-hard zone claims so parallel agents never touch the same symbol. How Aura Crew does it.
Goal-based agent loops: giving a coding agent a definition of done
A goal-based loop keeps a coding agent iterating until a success criterion is met. The trick is a deterministic definition of done — tests, a score, a proof — not an LLM guessing at "good enough." How to write one.