Claude Code worktrees: parallel agents without the conflicts

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:

# one branch + worktree per task
git worktree add ../repo-feature-auth -b feature/auth
git worktree add ../repo-refactor-db -b refactor/db-layer
git worktree add ../repo-fix-api -b fix/api-timeout

# each agent runs in its own directory
cd ../repo-feature-auth && claude  # agent 1
cd ../repo-refactor-db && claude   # agent 2, separate terminal
cd ../repo-fix-api && claude       # agent 3, separate terminal

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:

# review what agent 1 did
git -C ../repo-feature-auth log --oneline

# merge into main and remove the worktree
git merge feature/auth
git worktree remove ../repo-feature-auth
git branch -d feature/auth

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.

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.

Where the tooling takes over

The worktree workflow described above is what running parallel Claude Code agents looks like without an orchestration layer. It works, and it is worth understanding well — the mechanics are the same regardless of what tooling you add on top.

defract is built on the same pattern: each task gets its own git worktree, each agent runs in isolation, and merges happen through a review gate. The difference is that defract manages the lifecycle — creating and naming worktrees, propagating shared decisions into each agent's context, surfacing the merge sequence, and running a review agent against each branch before it hits your queue. The worktree bookkeeping that you would otherwise track in a separate document is handled by the pipeline. You see tasks as stages — design, architecture, implementation, review — not as a set of directories and branches to coordinate manually.

If you are running Claude Code agents in worktrees today and the overhead is starting to exceed the throughput benefit, defract is the direct answer to that problem. The workflow is the same; the coordination layer is not yours to maintain.