Claude Code Running Multiple Agents: Worktrees & Merges

Key takeaways

• Give every Claude Code agent its own git worktree and branch so edits, indexes, and uncommitted state never collide.
• Split parallel work by file ownership, not by feature, and write acceptance criteria agents can verify themselves.
• Serialize merges: one branch enters main at a time, smallest diff first, with the agent resolving its own rebase conflicts.
• Token burn scales roughly with agent count, so poll sparingly and scope each session's context to its task files.
• Three agents is a practical starting point; API rate limits and your review bandwidth bottleneck before compute does.

Claude code running multiple agents works when each agent gets its own git worktree, a task scoped so it touches distinct files, and a merge order you decide before agents start. Get those three things wrong and you get collisions, conflicts, and context drift. This playbook covers the setup and the failure modes the official docs skip.

When does running multiple Claude Code agents actually pay off?

Parallel agents pay off when your backlog has tasks that touch different files and can each be verified against clear acceptance criteria. If every ticket depends on the last one, or review is still serial (you), extra agents just queue up waiting on you.

The math changes once agent time exceeds your coordination time. Anthropic's own docs recommend separate Claude Code sessions with isolated context for independent tasks (Claude Code docs). In practice that means: three or more independent tickets, git worktrees per agent so edits don't collide, and a way to review diffs as they land rather than one mega-merge on Friday.

It's not worth it for exploratory work or a single tight refactor. One agent, one thread of context, wins there. Once you're queuing prompts by hand across six terminals, an orchestration layer like instant feedback for coding agents keeps agents busy while you stay on review.

How do you isolate agents with git worktrees so they don't collide?

Two Claude Code agents editing the same checkout will stomp each other: one reformats a file while the other diffs it, and both see half-applied changes. The fix is git worktree add ../feature-auth feature-auth, one branch and directory per agent. Each agent gets its own working tree, its own index, and its own uncommitted state, while sharing the same object store and remotes. Spawning from the repo root means every agent after the first needs --allow-multiple-sessions or a separate directory, and the worktree is the separate directory.

Setting up a worktree per agent

Create one branch per Linear ticket before spawning anything: git worktree add ../repo-auth auth-ticket-482, then cd ../repo-auth && claude. Name directories after the ticket, not the agent, so a stale worktree tells you which task it belonged to. Run git worktree list to see what is live, and git worktree remove ../repo-auth once the branch is merged. Keep each agent's build artifacts and node_modules inside its worktree; sharing a single dist/ or lockfile across worktrees reintroduces the collision you just solved.

What breaks without isolation

The failure is quiet until it isn't. Agent A runs a migration script that edits a shared config file; Agent B reads the half-edited version, builds on wrong assumptions, and both commits look locally correct. You spend the review session doing archaeology instead of reviewing the diff. Uncommitted changes from one agent can also leak into another's context window if they share a directory, so the model reasons about work that was never assigned to it. If you review parallel output through pull requests, the isolation rule extends there too: one branch, one diff, one purpose per PR (https://aerunit.ai/fr/reviewing-agent-pull-requests). Worktrees are cheap, so when in doubt, make another.

How should you split a task so parallel agents don't duplicate work?

Split by file ownership, not by feature enthusiasm. If two agents can edit the same file, they will, and the second merge becomes archaeology. A workable rule: one story touches one bounded area, and before you hit enter on a second agent, check that their file sets don't overlap. Overlap means the work isn't split yet.

File ownership boundaries

Draw boundaries where the code already has them: routes, packages, migration folders, test directories. If your split crosses a shared module, that module is the coupling point. Either assign it to one agent and have the other read it, or split sequentially. Git's own model supports this: each worktree is a linked working directory with its own checked-out branch, so isolation at the branch level only works if the file-level split came first.

Writing acceptance criteria agents can verify

"I got tired of waiting around just to paste in the next prompt" is a queueing problem, but "How do I know the implementation is actually complete?" is a spec problem. Write criteria the agent can check itself: tests that must pass, commands that must run, endpoints that must respond. Vague criteria produce confident agents with unfinished work.

When a story genuinely can't be split, run it solo and queue the next independent story instead. Burning tokens on two agents editing one file costs more than it saves, a trade-off we break down in coding agent costs.

How do you coordinate merges when several agents finish at once?

Treat merging as a serialized step. Agents can finish in any order, but exactly one branch enters main at a time, and whoever merges rebases onto the latest main first. If you let two agents push in parallel, you get race conditions on the remote and conflicts nobody can attribute.

Merge order and rebase strategy

Merge in completion order, smallest diff first. A 40-line fix that touches one module rebases cleanly; a 600-line refactor will fight with everything behind it. Before each merge, have the agent run git rebase main and the test suite, then push. If the rebase produces conflicts, do not hand-resolve them yourself mid-queue. Reject the branch back to the agent with the conflict list in the prompt and let it re-apply its own changes. This is the same scoping discipline as task decomposition: the agent that wrote the code resolves its own conflicts better than you do from memory.

When two agents touched the same file

Conflicts here usually mean your task split leaked. Two agents editing the same file were not independent, and the second one was planned against a stale version. Merge the first branch, then rebase the second and have the agent re-read the file before continuing. If the same file keeps colliding across tasks, stop merging and re-split the remaining work along file boundaries instead. Writing acceptance criteria per task, including "touches only these paths", prevents most of this before agents start; the task briefs pattern at Aerunit covers how to scope that.

What does a shared task queue or orchestration layer add over manual spawning?

Manual terminals vs a queue

Manual spawning works until it doesn't. Two or three agents in separate worktrees are manageable by hand; past that, you become the queue, pasting the next prompt into whichever terminal finished first and re-checking every diff. A queue inverts that: tasks carry acceptance criteria, agents pull the next scoped item when they finish, and you intervene only on review. The cost side matters too, because idle agents polling for work still burn tokens at Claude API rates (Anthropic's pricing page).

Tools compared honestly

	Manual terminals	Kanban/queue tools	Orchestration products
Setup	None	Low	Medium
Cross-repo awareness	You	Varies	Built in
Team credit pooling	No	Rare	Yes
Fit for 2-10 person Linear teams	Fine at 2 agents	Good	Good

Queue tools and orchestration products like Conductor or Aerunit differ mainly in how much workflow they impose. Aerunit's trade-offs: it presupposes Linear and Cursor Cloud Agents, so a Claude Code-only team gets less value, and its credit-pool pricing assumes a team, which is friction for a solo founder. The deeper mechanics of running parallel agents are covered in our guide to parallel coding agents.

How do you review and trust output from many parallel agents?

Review the diff, not the summary. An agent that says "done" has only finished generating tokens; your acceptance criteria live in the diff, the tests, and the branch state. Make every agent open a pull request against its worktree branch so you review in one place, and reject anything without a passing test run attached.

Add a verification step between "agent finished" and "ready to merge": run the test suite and type checker, check for stubbed or skipped tests, and confirm the task's acceptance criteria are actually met. This is the gap most people hit first. One builder of an agent kanban board asked plainly, "How do I know the implementation is actually complete?" (Reddit r/opensource)

Two failure modes catch most incomplete work. First, context degradation: an early mistake in file structure propagates through every queued prompt, so verify the first step before letting the queue run. Second, silent partial completion, where the agent implements three of four criteria and stops. A checklist per task, written before you spawn the agent, turns both into mechanical checks instead of vibes.

What does running multiple agents cost in tokens and compute?

Each parallel session re-reads context on every turn, so five agents on the same repo burn roughly five times the tokens of one, plus whatever polling costs. A loop that checks agent status every 30 seconds pays for a model call each time; polling burns tokens even when nothing changed. Watch your provider dashboard during your first parallel run and note the per-hour burn before scaling past three agents.

Three tactics keep it sane. First, poll less: check every few minutes or use hooks/notifications instead of tight loops. Second, scope context: point each agent at its worktree and only the files its task touches, not the whole repo. Third, queue prompts as a batch rather than babysitting each turn, so you pay for agent work, not for your waiting time.

Compute is the cheaper half: Claude Code runs locally, so the real bill is API tokens plus your CI minutes if agents push branches that trigger builds.

FAQ

Can Claude Code run multiple agents in the same repo at the same time?

Yes, but not in the same checkout. Give each agent its own git worktree and branch so edits, uncommitted state, and indexes stay separate while the object store is shared. Two agents in one directory will stomp each other's diffs and reason about work that was never assigned to them.

How many Claude Code agents can I run before my machine or rate limits give out?

Three is a practical starting point, since each session re-reads context every turn and token burn scales roughly with agent count. Compute is rarely the bottleneck because Claude Code runs locally; API rate limits and your review bandwidth are. Watch the provider dashboard during your first run before scaling past three.

Do Claude Code subagents count as running multiple agents, or do I need separate sessions?

Subagents run inside one session and share its context, so they don't give you the isolation parallel work needs. For independent tasks you want separate Claude Code sessions, each in its own worktree with a scoped task. Subagents are fine for delegated research or subtasks that feed one thread of work.

What's the best way to queue the next prompt without sitting at the terminal?

Batch your prompts instead of pasting one per turn, or use hooks and notifications so finished agents ping you. Past two or three agents, a task queue helps: items carry acceptance criteria, agents pull the next scoped task when done, and you only intervene on review. Idle polling still burns tokens, so poll every few minutes at most.

How do I stop context drift when chaining prompts across agent sessions?

Verify the first step before letting the queue run, because an early structural mistake propagates through every later prompt. Scope each session's context to its worktree and only the files its task touches. Write acceptance criteria before spawning, and treat silent partial completion, where an agent meets three of four criteria, as a checklist problem rather than a vibes problem.