# 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.

- **Category:** [Coding](https://stepgleam.com/categories/coding)
- **Difficulty:** Advanced
- **Time:** ~45 minutes
- **Tools:** Claude Code, Git, Codex
- **Reliability score:** 82/100
- **Steps:** 6
- **Last updated:** 2026-10-26
- **Published:** 2026-10-26

## Tools used

- [Claude Code](https://code.claude.com/docs) — Runs each session in its own worktree
- [Git](https://git-scm.com) — Worktrees, branches and rebases
- [Codex](https://developers.openai.com/codex) — Optional second-model review of each PR

## What you'll get

Independent branches from parallel sessions, merged one at a time with the full test suite run on the merged state.

## Who this is for

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.

## Steps

### Step 1: Start each session in its own worktree

**Tool:** Claude Code

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."*

**Why this works:** Separate checkouts mean edits cannot collide.

**Prompt:**

```
claude --worktree feature-auth
```

[Open step 1](https://stepgleam.com/guides/run-parallel-claude-code-agents-in-git-worktrees#step-1)

### Step 2: Have each agent list the files it expects to touch

**Tool:** Claude Code

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."*

**Prompt:**

```
Before you change anything, list the files you expect to create or modify for this task.
```

[Open step 2](https://stepgleam.com/guides/run-parallel-claude-code-agents-in-git-worktrees#step-2)

### Step 3: 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"*.

[Open step 3](https://stepgleam.com/guides/run-parallel-claude-code-agents-in-git-worktrees#step-3)

### Step 4: 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.

[Open step 4](https://stepgleam.com/guides/run-parallel-claude-code-agents-in-git-worktrees#step-4)

### Step 5: Merge one stream, rebase the rest, repeat

**Tool:** Git

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.

[Open step 5](https://stepgleam.com/guides/run-parallel-claude-code-agents-in-git-worktrees#step-5)

### Step 6: 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.

[Open step 6](https://stepgleam.com/guides/run-parallel-claude-code-agents-in-git-worktrees#step-6)

## Pro tips

- Name worktrees after the task so they are easy to resume.
- Debugging chains do not parallelise; one agent should own the hypothesis loop.

## Common mistakes

- Running two refactors at once.
- Merging every branch at the end instead of one at a time.
- Letting two agents edit the schema.

## FAQ

### Do I need the --worktree flag?

No, plain git worktree works too; the flag sets up the folder and branch for you.

### How many agents?

The developers quoted here stop at two to four.

---

Canonical guide: https://stepgleam.com/guides/run-parallel-claude-code-agents-in-git-worktrees
Read this guide as Markdown: https://stepgleam.com/guides/run-parallel-claude-code-agents-in-git-worktrees.md