How to Run Multiple Claude Code Agents in Parallel with Git Worktrees

Mar 21, 2026

I stared at the error message on my terminal. Two Claude Code agents were trying to edit the same file simultaneously, and the result was a mess of conflicting changes.

error: Your local changes to 'src/auth/login.ts' would be overwritten by merge

I had been running multiple Claude Code sessions in different terminal tabs, thinking I could speed up my workflow by having one agent refactor the authentication module while another worked on adding tests. But they were both operating in the same working directory, and chaos ensued.

The Problem: Claude Code Wants Exclusive Access

Claude Code maintains session state in a single working directory. When you run it, it assumes it has exclusive control over the files in that directory. Running two instances in the same folder is like having two developers type in the same file at the same time—nothing good comes from it.

I tried switching between tasks manually. I’d start one agent, pause it, switch branches, start another agent. The context-switching overhead was brutal. Each time I switched, I lost the mental model the previous agent had built. Plus, context window limits meant I couldn’t just explain everything to a single agent and expect it to handle multiple independent tasks.

What I needed was a way to give each Claude Code agent its own isolated workspace—while still working on the same repository.

Git Worktrees: The Missing Piece

Git worktrees solved this problem perfectly. A worktree lets you check out the same repository into multiple directories, each on its own branch. Each worktree is a fully independent working directory that shares the same Git history.

Here’s how I set it up:

# Create a worktree for my authentication refactor task
git worktree add ../auth-refactor -b feature/auth-refactor

# Navigate to the new worktree
cd ../auth-refactor

# Start Claude Code in this isolated environment
claude

Now Claude Code runs in ../auth-refactor, completely isolated from my main project directory. I can start another agent in a different worktree for a different task:

# From the main repo, create another worktree for tests
git worktree add ../auth-tests -b feature/auth-tests

cd ../auth-tests
claude

I now have two Claude Code agents running in parallel, each in its own workspace, working on independent tasks.

Viewing Your Worktrees

To see all active worktrees:

git worktree list

Output:

/Users/projects/my-app         abc1234 [main]
/Users/projects/auth-refactor  def5678 [feature/auth-refactor]
/Users/projects/auth-tests     ghi9012 [feature/auth-tests]

Each entry shows the path, current commit hash, and branch name.

Running Parallel Agents with tmux

I use tmux to manage multiple Claude Code sessions. Here’s my setup:

# Create a new tmux session for agents
tmux new-session -s claude-agents

# Split into panes (Ctrl+b % for vertical, Ctrl+b " for horizontal)
# Then in each pane, navigate to a different worktree and start Claude

In pane 1:

cd /Users/projects/auth-refactor
claude

In pane 2:

cd /Users/projects/auth-tests
claude

Now I have two agents running side by side, visible in the same terminal window, each working independently.

Merging the Results

When an agent finishes its task, I merge its changes back:

# Return to main worktree
cd /Users/projects/my-app

# Merge the agent's branch
git merge feature/auth-refactor

If there are conflicts, Git will flag them and I can resolve them manually. The key insight from Citadel’s Fleet mode implementation: with proper task isolation, conflicts are surprisingly rare. Citadel reported only a 3.1% conflict rate across 109 parallel agent waves.

After merging, clean up:

# Remove the worktree
git worktree remove ../auth-refactor

# Delete the branch
git branch -d feature/auth-refactor

Why This Works So Well

The benefits became obvious after a few days of using this approach:

True Parallelism: Tasks that would have taken 4 hours sequentially now complete in 1.5 hours. I can have one agent writing code while another writes tests for a different module.

Context Isolation: Each agent has a clean, focused context. The authentication refactor agent doesn’t get confused by unrelated database migration discussions from the testing agent.

Flexibility: If one agent gets stuck or needs my input, I can pause it and let the others continue. No all-or-nothing blocking.

Low Conflict Rate: Because each worktree is on its own branch targeting a specific task, merge conflicts are rare. The 3.1% rate reported by Fleet users matches my experience.

Common Mistakes I Made

Creating worktrees on the same branch: This causes problems. Each worktree must have its own branch. The -b flag in git worktree add creates a new branch automatically.

Forgetting to prune old worktrees: After merging, old worktrees linger. I added a weekly reminder to run git worktree prune to clean up references to deleted worktrees.

Not planning file boundaries: Agents editing the same file in different worktrees will conflict on merge. I now think about which files each agent will touch before spawning them.

Merging without review: Agent-generated code isn’t always perfect. I always review the diff before merging: git diff main...feature/auth-refactor.

Reference Links

Git Worktree Documentation - Official Git documentation for worktree commands
Claude Code Documentation - Official Claude Code usage guide
Citadel Fleet Mode Discussion - Reddit thread discussing parallel agent orchestration with Fleet mode

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!