# Give each parallel coding agent its own git worktree, then review and merge

> Create one git worktree and branch per agent, let each agent commit there, review each branch, merge them one at a time and remove the worktrees; worktrees isolate files only.

## Answer

Give every agent its own git worktree, which is a separate working directory with its own branch that shares the repository history. Two agents then never edit the same files on disk. In Claude Code, `claude --worktree <name>` does this for you. Plain git does it with `git worktree add ../dir -b branch`. Each agent's work reaches `main` only when you review and merge its branch. Checked 2026-09-28 against Claude Code 2.1.284 and git 2.43.0 (the git docs describe 2.54).

## Details

### Two ways to create the worktrees

| | Claude Code | Plain git |
|---|---|---|
| Command | `claude --worktree feature-auth` | `git worktree add ../project-feature-a -b feature-a` |
| Location | `.claude/worktrees/<name>/` | Wherever you point it |
| Branch | `worktree-<name>` | The name you give |
| Base | Remote default branch; `worktree.baseRef: "head"` uses your local `HEAD` | Current `HEAD`, or a commit-ish you pass |

Claude Code can also copy ignored files such as `.env` into each new worktree. List them in a `.worktreeinclude` file at the project root, using `.gitignore` syntax. A custom subagent gets its own worktree when its frontmatter says `isolation: worktree`. Add `.claude/worktrees/` to `.gitignore`.

### Worked example: three agents

I ran these plain git commands in a throwaway repository with one commit. Agent A and agent C edit the same line, on purpose.

1. Create three worktrees.

```text
$ git worktree add ../wt-demo-a -b agent-a
Preparing worktree (new branch 'agent-a')
$ git worktree list
/tmp/wt-demo    b521497 [main]
/tmp/wt-demo-a  b521497 [agent-a]
/tmp/wt-demo-b  b521497 [agent-b]
/tmp/wt-demo-c  b521497 [agent-c]
```

2. Start one agent in each directory. Each one commits on its own branch.
3. Review from the main checkout, for example `git log --oneline main..agent-a` and `git diff --stat main...agent-b`.
4. Merge one branch at a time. A and B merged cleanly. C did not:

```text
$ git merge --no-ff -m "Merge agent-c" agent-c
Auto-merging app.py
CONFLICT (content): Merge conflict in app.py
Automatic merge failed; fix conflicts and then commit the result.
```

I ran `git merge --abort` here. In real work, resolve the conflict, or ask agent C to rebase onto the new `main`.

5. Remove the worktrees. Git refuses if one is unclean:

```text
$ git worktree remove ../wt-demo-c
fatal: '../wt-demo-c' contains modified or untracked files, use --force to delete it
```

Use `--force` only after you have saved what you need. Then delete merged branches with `git branch -d`. It refused for `agent-c`, "not fully merged", because that merge was aborted.

Git also refuses to check the same branch out in two worktrees: `fatal: 'agent-a' is already used by worktree at '/tmp/wt-demo-a'`.

### What worktrees do not isolate

- **The shared `.git` directory.** Refs and repository config are shared. A `git commit` in one worktree writes to the same repository.
- **Permission approvals.** In Claude Code, "Yes, and don't ask again" saves the rule to the main checkout, so it applies in every worktree.
- **Ports.** Two dev servers on port 3000 still collide.
- **Databases and caches** outside the directory, such as a local database or a global package cache.
- **Installed dependencies.** A worktree is a fresh checkout, so run the install step in each one.
- **The rest of your machine.** Worktrees are not a security boundary. See [[run-coding-agent-safely-sandbox-container]].

### Common mistakes

- Giving two agents overlapping files, then merging late. Split tasks by file or module.
- Merging all branches at once. Merge one, rerun tests, then the next.
- Forgetting that `worktree.baseRef` defaults to the remote default branch, so unpushed local commits are missing.
- Deleting a worktree with `--force` before committing its work.

## See also

- [[when-to-use-multi-agent]]
- [[run-coding-agent-safely-sandbox-container]]
- [[claude-code-skills-vs-subagents-vs-hooks]]
- [[agent-stuck-in-loop-troubleshooting]]

## Sources

- [Claude Code — Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees)
- [Git — git-worktree documentation](https://git-scm.com/docs/git-worktree)
- [Hacker News — Show HN: wt, a lightweight Git worktree orchestrator for parallel coding agents](https://news.ycombinator.com/item?id=46765489)
- [Hacker News — Git worktrees are not an isolation boundary for coding agents](https://news.ycombinator.com/item?id=49110389)

## Sources

- [Claude Code — Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees)
- [Git — git-worktree documentation](https://git-scm.com/docs/git-worktree)
- [Hacker News — Show HN: wt, a lightweight Git worktree orchestrator for parallel coding agents](https://news.ycombinator.com/item?id=46765489)
- [Hacker News — Git worktrees are not an isolation boundary for coding agents](https://news.ycombinator.com/item?id=49110389)