The first time you run two Claude Code agents at once, it usually works fine. Each one has a task, each one works through it, and you review two outputs instead of one. You get the work done faster.
The problem appears when agent A and agent B edit the same file. One agent's changes overwrite the other's. Or they both commit, and now you have a conflict that neither agent created intentionally but that you have to untangle manually. The more agents you run, the more likely this becomes. Scaling past a handful of parallel agents without some kind of isolation is a coordination problem waiting to happen.
What git worktrees actually do
A git worktree is an additional working directory tied to the same repository. The repository has one object store — one set of commits, branches, and history — but multiple on-disk checkouts, each on a different branch, each with its own working tree and index. You can have ten worktrees open at once, each pointing to a different branch, none of them interfering with each other's file state.
For parallel Claude Code agents, the implication is direct. Instead of multiple agents operating in the same directory, each agent gets its own worktree on its own branch. Agent A modifies files in ../repo-feature-auth; agent B modifies files in ../repo-refactor-db; your main checkout at ../repo stays clean. No shared mutable state. No mid-run file conflicts. Isolation by design.
Setting up the workflow
The mechanics are straightforward. For each parallel task, you create a branch and a worktree before you launch the agent:
Each Claude Code session sees exactly one working directory. It reads files, edits them, commits to its branch. None of those file changes propagate to the other worktrees until you explicitly merge. The agents are genuinely parallel — they can write to the same filenames in their respective directories without any coordination required.
When an agent finishes, you review its branch, merge or rebase it, and clean up the worktree:
This is the core of the worktree workflow. Most explanations stop here. The harder part is what comes next.
The merge sequence problem
Worktrees isolate agents from each other during execution. They do not eliminate the merge work that comes after. If agents A, B, and C all modified different files, your merge sequence is straightforward. If any two of them touched overlapping code — even in ways that make individual sense — the merge is a judgment call you make by hand.
Worktrees defer this to the end rather than surfacing it mid-run. That is strictly better: a conflict at merge time is one you can reason about with full context, not one that interrupts an agent mid-task. But "deferred" is not "eliminated." The merge work is still there, and it scales with the number of parallel agents and the surface area they touched.
One practical approach: sequence your merges fastest-to-slowest. The task most likely to finish first is usually the smallest or most independent. Merging it early reduces the surface area that later merges have to reconcile. Keeping a written or annotated task list that tracks which branches touched which modules helps you sequence correctly — especially past three or four parallel agents.
The context coordination problem
The deeper problem with parallel agents is not the file conflicts — worktrees solve those. It is that each Claude Code session has its own context window. When agent A decides "we prefix these functions with handle_," that decision lives in agent A's session. Agent B, in its own worktree, will make a different choice — not because it disagreed, but because it was never told.
This is the decision-consistency problem that worktrees do not touch. The isolation that prevents file conflicts also prevents agents from sharing knowledge. You end up with two branches that merge cleanly at the file level but contradict each other at the design level. The naming convention mismatch, the duplicated helper, the interface that two agents built differently from the same spec — these surface at merge time as a review problem, not a conflict marker.
The standard fix is to front-load shared decisions. Before parallel work starts, you define and write down the interfaces, naming conventions, and constraints each agent must respect. You give each agent that document as context at session start. This is the same principle as the architecture-before-implementation pattern: settle the shared surface area before agents diverge, so they diverge on safe ground.
The bookkeeping overhead
Running three to five parallel agents in worktrees is manageable. Running more starts to carry bookkeeping overhead that compounds. Which worktree is for which task. Which branches are still in flight. Which agents are waiting on a decision. Which merges are blocked on which other merges. Where the shared context document lives and whether each agent received an updated version after the last decision.
None of this is hard in isolation. The problem is that it is all yours to manage, in your head or in a separate document, while also reviewing agent output and making product decisions. The scale at which parallel agents break down is often not technical — it is cognitive. You become the coordination layer that the agents cannot be for each other.
what the practical ceiling looks like: most developers running Claude Code agents in worktrees find the overhead manageable to about 3–4 parallel tasks. past that, the bookkeeping — which branches are live, which shared decisions need propagating, which merge is next — starts to take as long as the actual review work.
The worktree-complete workflow
Putting it together, a worktree workflow that actually works at scale has a few consistent properties:
- One worktree per task, one branch per worktree. Never two agents in the same directory. Name branches after the task, not the agent — the task is the durable thing.
- Shared context delivered up front. Before any agent starts, it receives the current decisions document — naming conventions, interface contracts, which files are off-limits for which agents. This is a file, not a conversation; conversations don't survive session restarts.
- A written merge sequence. Before parallel work starts, you know which branch can merge first and why. Independent tasks can merge in any order; dependent tasks have an explicit ordering you respect.
- A running task list external to the agents. Which branches are active, which are done, which are blocked. This is bookkeeping, not product thinking, but it is yours to do — the agents cannot see each other's state.
- Review before merge. Each branch gets a review pass — either yours or a review agent running in the same worktree — before it enters main. Worktrees make this cheap: the branch is already isolated, so the review agent has clean context and no noise from other in-flight work.
This workflow is reliable. It is also manual. Every worktree is created by hand. Every context document is maintained by hand. Every merge sequence is decided by hand. The agents do the implementation work; the orchestration is on you.
Top comments (2)
I really appreciate how this article highlights the importance of worktrees in preventing file conflicts when running parallel Claude Code agents, and I'm intrigued by the discussion on the merge sequence problem. I'm wondering, have you found any additional strategies for sequencing merges that help minimize the complexity of reconciling overlapping changes, beyond just merging the fastest-to-slowest tasks?
honestly the biggest lever is upstream, not at merge time: scope the tasks to disjoint file boundaries when you fan them out and the agents mostly don't collide, so merge order stops mattering. when they do share surface, i rebase each branch onto main right before it merges instead of doing one big merge at the end, so conflicts show up small and one at a time. curious how many agents you're running in parallel?