Run parallel Claude Code agents in git worktrees without merge hell
Give each agent its own worktree, scope tasks so their files do not overlap, merge one stream at a time, and rebase the rest on the new main.
Tools used
- Claude CodeRuns each session in its own worktree
- GitWorktrees, branches and rebases
- CodexOptional second-model review of each PR
Step navigator
Independent branches from parallel sessions, merged one at a time with the full test suite run on the merged state.
Developers comfortable with one Claude Code session who want to run more.
Before you start
Several developers on r/ClaudeAI and r/ClaudeCode run two to four Claude Code sessions at once. Their shared lesson: worktrees stop file collisions, but scoping decides whether the merge goes well. Claude Code's docs cover the built-in --worktree flag.
Step-by-step instructions
Start each session in its own worktree
Run claude --worktree <name> in separate terminals. Each gets its own checkout under .claude/worktrees/<name>/ on a new branch; add .claude/worktrees/ to .gitignore. A user who found the flag: "Since v2.1.49, Claude Code has this built in."
claude --worktree feature-auth
Why this works
Separate checkouts mean edits cannot collide.
Have each agent list the files it expects to touch
Before letting agents loose, "get it to write out the files it expects to touch. If those sets overlap by more than a couple, you're going to merge-hell yourself no matter how clean the worktree setup is."
Before you change anything, list the files you expect to create or modify for this task.
Only run genuinely independent work in parallel
The same developer's list of what parallelises reliably: different routes or pages, frontend vs backend on one feature, tests on one module while another gets the feature, docs while code is written. What goes sideways: "Anything touching shared types or schemas", "Two refactors at once", "Migrations in parallel".
Give shared boundaries one owner
Another user keeps "one explicit owner for shared boundaries like schema, auth, config, and migrations"; other agents leave notes there instead of editing that surface.
Why this works
A change to a shared type silently invalidates the other agents' plans.
Merge one stream, rebase the rest, repeat
A developer who ran four streams on a 50k-line project: open a PR per stream, tag Codex to challenge it, "Merge that stream first", "Rebase the remaining streams on the new main", repeat. Run the full suite on the merged result.
Stop at the number you can actually track
The same developer capped out at four agents: "Not a tooling limit, a cognitive one." Plan usage limits were the other ceiling.
End of guide · Reviewed Oct 26, 2026
Pro tips2
- Name worktrees after the task so they are easy to resume.
- Debugging chains do not parallelise; one agent should own the hypothesis loop.
Common mistakes3
- Running two refactors at once.
- Merging every branch at the end instead of one at a time.
- Letting two agents edit the schema.
FAQ2
Do I need the --worktree flag?
How many agents?
Related field guides.
CodingGet a second-opinion review from a fresh session or another model
Review the agent's diff in a session that didn't write it, either a fresh Claude Code session or Codex on the PR, and act only on findings that affect correctness.
CodingSet up Claude Code hooks for formatting, tests and protected files
Add PostToolUse hooks that format and test after edits, a PreToolUse hook that blocks protected files, and a notification for long runs.
CodingTurn a checklist you keep forgetting into a Claude Code skill
When you catch yourself re-typing the same multi-step instructions, put them in .claude/skills/<name>/SKILL.md and run them with a slash command.