<!-- Claude Code worktrees: merging parallel agent branches · https://merget.ai/guides/claude-code-worktrees-merge -->

# Merging git worktrees from parallel Claude Code agents

Claude Code’s --worktree flag gives each session its own checkout and branch. Set them up, land the branches, and stop them colliding at merge time.

Merget team · Nov 13, 2026 · 4 min read

Start each Claude Code session with `claude --worktree <name>` so it gets its own checkout and branch, open a pull request from each branch, and land the pull requests through a merge queue that resolves the conflicts between them. Worktrees stop sessions overwriting each other’s files; they do not stop the branches conflicting when they merge.

## What a worktree gives a Claude Code session

A git worktree is a separate working directory with its own files and branch, sharing one repository history. Claude Code creates one for you:

```
claude --worktree feature-auth

# in a second terminal
claude --worktree fix-logout
```

By default each worktree is created under `.claude/worktrees/<name>/` at the repository root, on a new branch named `worktree-<name>`. Leave the name off and Claude Code generates one. New worktrees branch from the repository’s default branch; set `worktree.baseRef` to `"head"` to branch from your current work instead. See the [Claude Code worktree docs](https://code.claude.com/docs/en/worktrees).

## Set up each worktree once

- Add `.claude/worktrees/` to `.gitignore` so worktree contents do not show up as untracked files.
- List gitignored files a session needs, such as `.env`, in a `.worktreeinclude` file at the project root. Claude Code copies them into each new worktree.
- Install dependencies in the worktree. It is a fresh checkout.
- For subagents, add `isolation: worktree` to the subagent’s frontmatter, or ask Claude to “use worktrees for your agents”.

## Land each branch as a pull request

When a session finishes, ask it to create a pull request. One pull request per worktree keeps changes small and reviewable. To pick up an existing pull request in its own worktree, run `claude --worktree "#1234"`.

When you exit, Claude Code removes a clean worktree and its branch, and asks whether to keep one that still holds work. Use `git worktree list` to see what is left and `git worktree remove` to clean up by hand.

## A workflow for five or more sessions

1. Split the work into tasks that touch different areas of the code where you can.
2. Start one worktree session per task and name it for the task, so the branch and the pull request are easy to recognize.
3. Ask each session to run the tests in its worktree before it opens a pull request.
4. Keep each pull request to one task. Small pull requests conflict less and are quicker to review.
5. Exit finished sessions. Claude Code removes worktrees that have nothing left in them.

Sessions can also pass findings to each other with cross-session messaging, which helps them avoid duplicate work. It does not change what happens at merge time: each branch was still written against an older main.

## Why the branches still conflict

Every worktree branched from the same main. The first pull request to land moves main, and every other branch is now behind it. If two sessions touched the same lines, Git reports a textual conflict. If one renamed a function and another added a call to its old name, Git merges both cleanly and the build breaks. That second kind is a [semantic conflict](https://merget.ai/semantic-merge-queue).

It is common with agents. In a replay study of agent pull requests, pairs from different agents hit textual conflicts in 41.7% of cases, against 19.8% for pairs from the same agent ([Xu et al., 2026](https://arxiv.org/abs/2607.04697)).

## Four ways to merge the worktrees

| Approach | How it works | Where it strains |
| --- | --- | --- |
| Merge one at a time | Land a pull request, rebase the rest, rerun CI, repeat. | Every landing sends the other sessions back to rebase. |
| One integration session | A final Claude Code session merges every branch and fixes what breaks. | One long session holds all the context, and it starts again when main moves. |
| GitHub merge queue | Queues pull requests and tests them together before merging. | A pull request that conflicts is removed from the queue and goes back to its author. |
| Merget | Finds the pull requests that collide and resolves the conflicts in queue order. | What it cannot resolve safely comes back to a person. |

## Let the queue reconcile the branches

[Merget](https://merget.ai/how-it-works) is a semantic merge queue for GitHub. It finds the pull requests that collide, including the ones Git merges cleanly, resolves the conflicts in queue order, and lands the result through your required checks and reviews. No label, comment or enqueue command is needed, and your sessions keep working in their worktrees.

Merget starts in Advisory mode, where it reports the conflicts and changes no source code. To give your agent the queue’s findings and order, paste this into it:

```
Fetch and execute the instructions to set me up for Merget from https://sema.merget.ai/agent-setup/prompt.md
```

## What changes with a queue that resolves conflicts

Without one, every landing triggers a round of rebases, and each rebase is another agent session and another CI run. With one, the sessions stop when their pull request is open. The queue orders the pull requests, resolves the conflicts between them and reruns only what changed. In our benchmarks, Merget planned a queue of 40 merges in under 30 seconds and resolved [223 of 223 conflicted files](https://merget.ai/benchmarks/conflict-resolution) from real merges with one model call each.

If your sessions use Codex or Cursor as well, the same approach applies. See the [Codex worktrees guide](https://merget.ai/guides/codex-worktrees-merge) and the [Cursor worktrees guide](https://merget.ai/guides/cursor-worktrees-cloud-agents).

## Questions

### Do git worktrees prevent merge conflicts?

No. Worktrees isolate file edits while sessions run. The branches still conflict when they merge into main, because each started from the same commit.

### Where does Claude Code put worktrees?

Under `.claude/worktrees/<name>/` at the repository root by default, each on a branch named `worktree-<name>`.

### How many Claude Code sessions can I run in parallel?

Each `claude --worktree` session is independent, so the practical limit is your machine and how fast the resulting pull requests can land.

### Should each worktree be its own pull request?

Usually yes. Small pull requests are easier to review, and a merge queue can order and reconcile them.

[See how Merget resolves conflicts in queue order](https://merget.ai/how-it-works), or [sign up free](https://sema.merget.ai/login) and connect one repository.

### Claude Code agent teams: landing the pull requests

Agent teams coordinate the work between Claude Code sessions, not the merge. Set a team up, avoid overwrites, and land what it produces.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/claude-code-agent-teams-pull-requests)

### Codex worktrees: merging parallel agent branches

Codex runs each chat in its own git worktree so parallel tasks do not interfere. Turn the worktrees into pull requests and land them together.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/codex-worktrees-merge)

### Cursor worktrees and cloud agents: landing the pull requests

Cursor runs agents in git worktrees on your machine and in cloud VMs that push branches. See how both work and how to keep the pull requests landing.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/cursor-worktrees-cloud-agents)

[All guides](https://merget.ai/guides)
