~K¹yle Million

Posted on Apr 10

Claude Code Worktrees: How to Run Parallel Builds Without Merge Conflicts

#claudecode #devtools #aiagents #git

The Problem Nobody Talks About

You've set up Claude Code agents. Multiple instances, running in parallel, executing different parts of a build. Smart setup.

Then the first merge conflict hits.

Agent A was halfway through a feature. Agent B was refactoring the same file. Neither knew. Both checkpointed. Your main branch is now a crime scene.

Git worktrees fix this. They're not a new feature — they've been in Git since 2015. But most Claude Code operators aren't using them, and it shows.

This is the pattern that makes parallel agent builds actually work.

What Git Worktrees Actually Are

One repository, multiple working directories, each on its own branch.

git worktree add ../my-repo-feature-a feature-branch-a
git worktree add ../my-repo-feature-b feature-branch-b
git worktree list

Each worktree has:

Its own filesystem path
Its own branch (checked out exclusively — can't share with another worktree)
Its own working tree (uncommitted changes are isolated)
The same .git object store (no duplication of history)

Agent A works in ../my-repo-feature-a. Agent B works in ../my-repo-feature-b. They never touch the same files unless you merge. Zero conflict surface during parallel execution.

Why This Matters for Claude Code Specifically

Claude Code agents operate on files. When you run multiple agents in parallel — whether via Tmux panes, background tasks, or the Agent tool — they all write to the filesystem.

If they're working in the same directory, on the same branch, you get:

Write conflicts — two agents editing the same file simultaneously
Context corruption — Agent A reads a file mid-edit by Agent B, gets partial state
Checkpoint chaos — both agents commit, one overwrites the other's work
Merge hell — you manually reconcile two diverged histories

With worktrees:

Agent A gets worktrees/feature-a/ — its own branch, its own workspace
Agent B gets worktrees/feature-b/ — completely isolated
Both execute in parallel, no conflicts
You review and merge at the end, when both are complete

The isolation isn't a convenience. It's what makes autonomous parallel execution safe.

The Pattern: Worktree-Per-Agent

Here's the concrete setup for running two Claude Code agents in parallel on independent tasks:

Step 1: Create worktrees before spawning agents

# From your repo root
REPO=$(pwd)
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

git worktree add "$REPO/../worktree-agent-a-$TIMESTAMP" -b "agent-a-$TIMESTAMP"
git worktree add "$REPO/../worktree-agent-b-$TIMESTAMP" -b "agent-b-$TIMESTAMP"

Step 2: Point each agent at its worktree

In Tmux (two panes):

# Pane 1
cd ~/repo/../worktree-agent-a-20260410_090000
claude  # starts in isolated worktree, no conflict with pane 2

# Pane 2
cd ~/repo/../worktree-agent-b-20260410_090000
claude  # completely separate working tree

Or with headless invocation:

cd ~/repo/../worktree-agent-a-20260410_090000
claude -p "Build the authentication module. Write all files to this directory." \
  --allowedTools "Bash(*),Read(*),Write(*),Edit(*)"

Step 3: Review outputs, merge when ready

# Review agent A's work
git -C ~/repo log --oneline agent-a-20260410_090000

# Merge when satisfied
git checkout main
git merge agent-a-20260410_090000

# Clean up
git worktree remove ~/repo/../worktree-agent-a-20260410_090000
git branch -d agent-a-20260410_090000

Claude Code's Native Worktree Support

Claude Code ships with built-in worktree support in the Agent tool. When you spawn a sub-agent with isolation: "worktree", the system automatically:

Creates a temporary git worktree
Runs the agent in that isolated workspace
Returns the worktree path and branch name if changes were made
Cleans up automatically if the agent made no changes

Agent({
  description: "Build auth module",
  prompt: "Implement JWT authentication in src/auth/...",
  isolation: "worktree"
})

The automatic cleanup behavior is the key detail: if an agent is doing research or exploration (read-only), the worktree disappears when it's done. If it made changes, you get back the path to review and merge. Zero manual cleanup for exploratory work.

This is why the isolation: "worktree" parameter exists — Anthropic built it specifically for parallel agent execution.

When to Use Worktrees (And When Not To)

Use worktrees when:

Running two or more agents that will write to files
Agents are working on independent features or modules
You need to be able to reject an agent's output without touching your main branch
You're building something that takes multiple minutes and you want to run parallel tracks

Don't use worktrees when:

Agents are read-only (research, analysis, summarization)
The task is strictly sequential — Agent B's input depends on Agent A's output
The task is simple enough that one agent in main working tree is faster

The overhead of worktree creation (a few seconds) is worth it whenever the alternative is a merge conflict that costs you 15 minutes.

The Validation Pattern

Here's a pattern for any significant build: spawn a validator agent in a third worktree after the builder agents finish.

Builder Agent A (worktree-a) ──┐
                                ├──► Validator Agent (worktree-validator)
Builder Agent B (worktree-b) ──┘

The validator:

Reads both worktrees' outputs
Runs tests against each
Reports which passed, which failed, what conflicts would emerge on merge
Makes the merge recommendation

You get a CI-like gate before anything touches main, all within Claude Code, all autonomous.

Worktrees in Practice: The Inbox Processor Architecture

If you're running an inbox-based task system (where task files land in inbox/, get picked up, executed, output written to outputs/), worktrees let you handle multiple inbox tasks in parallel without any of them stepping on each other.

inbox/task_001.md ──► worktree/task_001/ ──► outputs/result_001.md
inbox/task_002.md ──► worktree/task_002/ ──► outputs/result_002.md
inbox/task_003.md ──► worktree/task_003/ ──► outputs/result_003.md
        (all three executing simultaneously)

Each task gets its own isolated branch. If task_002 fails midway, it doesn't corrupt task_001 or task_003. You can inspect the failed worktree's state, debug it, and retry without touching the others.

This is how you turn a sequential inbox processor into a parallel execution pipeline.

Common Mistakes

Mistake 1: Forgetting worktrees are exclusive

A branch can only be checked out in one worktree at a time. Try to create two worktrees on the same branch and Git will refuse. Use unique branch names per worktree (timestamps work well).

Mistake 2: Not cleaning up

Stale worktrees accumulate. Add cleanup to your completion logic:

git worktree prune  # removes entries for deleted directories
git worktree list   # audit what's still live

Mistake 3: Agents writing outside their worktree

If you give an agent a path outside its worktree, isolation breaks. Keep agent prompts scoped to their working directory. Tell the agent explicitly: "Write all output to the current directory."

Mistake 4: Merging without reviewing

Worktrees protect your main branch during execution, but they don't review for you. Always inspect the diff before merging an agent's worktree. git diff main..agent-branch before git merge.

The Payoff

Worktrees are infrastructure. You set them up once, they run every time, and they eliminate an entire class of failure that would otherwise require manual intervention.

The alternative — parallel agents in a shared working tree — produces coordination overhead that cancels out the parallelization benefit.