Run Parallel Claude Code Agents with Git Worktrees

Ask a chatbot how to run several Claude Code agents at once and you get a clean answer: give each agent its own git worktree so their edits don't collide, then merge the branches. That is correct, and Claude Code now has native worktree support that handles the mechanic for you — the official docs cover the --worktree flag and cleanup. What the setup guides leave out is the part that actually limits you: once the agents finish, you are the one who has to review and merge everything they produced.

How many agents can I actually run?

The honest answer is not a number of terminals; it is a number of diffs you can review per hour. Spinning up worktrees is cheap, so the agent count is never the constraint — your review throughput is. Each agent produces a branch that has to be read, understood, and judged before it merges, and that work is serial and falls entirely on you. Four agents that each need careful review can be slower than two you can keep up with.

A short test for your own ceiling: start with two parallel agents on genuinely independent slices and watch where the queue forms. If branches pile up unreviewed, you have found your limit, and adding a fifth agent makes it worse, not better. The thing to scale is how fast you can verify their output, which is why every agent needs a self-checking loop — tests it runs itself — so review is reading a green diff rather than re-deriving correctness by hand.

How do I merge their output without it turning into a mess?

This is the seam the setup guides skip. When you run several agents you stop being a typist and become the integrator, and integration is where parallel work goes wrong. The failure mode is well documented: AgenticFlict, a study of pull requests from AI coding agents, found a textual merge-conflict rate of 27.67% (arXiv:2604.03551) — more than one PR in four collided on merge. Agents in separate worktrees are blind to each other, so two of them editing the same function surfaces only when you try to combine the branches.

Merge in an order you control rather than all at once. Integrate one branch, run the suite, then rebase the next onto the result so each agent's work meets reality before the next lands. The cost of a conflict scales with how long you let branches drift, so merge small and often instead of letting four agents run to completion and integrating at the end.

How do I avoid conflicts in the first place?

Conflicts come from overlap, so the fix is at slice time, before any agent starts. Give each agent a slice that doesn't share files with the others — adding eval cases to eval/ while another agent edits app/triage/classify.py is safe; two agents both rewriting classify.py is not. If you can't name a clean seam between two tasks, they are one serial task and should not be parallelized.

Tooling can warn you early. Clash uses git merge-tree to run three-way merges between worktree pairs as the agents work, so overlapping edits show up before completion instead of at merge. Note what it does and does not do: it detects conflicts and surfaces them; it does not resolve or merge them for you. Early detection lets you re-slice or pause an agent, but the integration is still yours.

Worktrees vs subagents — which isolation do I want?

These solve different problems and the docs are explicit about it. A worktree isolates files: each session gets its own checkout and branch so edits never touch each other. A subagent coordinates work itself — one lead agent spawns helpers for parallelizable sub-tasks and collects their results, with the helpers acting as its tools. You can combine them: set isolation: worktree on a subagent and it gets its own checkout too. Reach for worktrees when you are running independent tasks you will merge yourself; reach for subagents when one driver is fanning out divisible work and gathering it back. The orchestration patterns page compares the approaches directly.

Go deeper

The reusable rule: scale review throughput, not terminal count, and merge in a controlled order so conflicts stay small. Isolation is the precondition; integration is the job. Module 5 teaches the full skill — slicing along seams, the orchestrator–worker pattern, and the lab that runs parallel agents on Triage and walks the merge. Next step: pick two independent slices in your own repo and run them in two worktrees, then time how long the review takes.