Parallel Claude Code sessions with git worktrees, two branches at once without conflict

You have two open threads in the repo, a feature and a bugfix, and both need Claude. You start two terminals, claude in both, and immediately both sessions are writing to the same files. Suddenly one session changes something the other was just about to read, and the state is gone. That is exactly what the --worktree flag is for, available since Claude Code v2.1.143. Every session gets its own working directory on its own branch and shares only the git history.

The pattern is not new, git worktree has been around since Git 2.5. What is new is that Claude Code now manages it for you, including cleanup, subagent isolation and a copy pattern for .env files. I have been using it in production for 3 weeks and can run 2 to 3 sessions in parallel per day without drift.

1. Check the prerequisites

You need Claude Code v2.1.143 at minimum and a git repo. Check:

claude --version
# must read >= 2.1.143, currently live is 2.1.148

If your version is older, update first. We have a playbook of its own for that: Claude Code update strategy. Outside a git repo --worktree does not work in default mode, you then need a WorktreeCreate hook for SVN/Mercurial/Perforce. For 95 percent of setups git is the default.

2. Accept the repo trust once

The first time you run it in a new directory, Claude throws up a workspace trust dialog. That has to be confirmed BEFORE you use --worktree, otherwise the command exits with an error. So, once:

cd /pfad/zu/deinem/repo
claude
# Trust-Dialog akzeptieren, danach Session beenden

This step cost me 15 minutes on my first attempt because I could not place the error. --worktree simply says "trust not accepted" and exits, and nowhere is that spelled out.

3. Extend your .gitignore

By default Claude puts worktrees under .claude/worktrees/<name>/. If you do not add that to .gitignore, all the worktree contents show up as untracked files in your main checkout and the status becomes unreadable. Add this one line:

.claude/worktrees/

That is the official recommendation and it is a one-liner, so please do not forget it.

4. Start your first worktree

In the main directory of your repo:

claude --worktree feature-auth

Claude now creates .claude/worktrees/feature-auth/, branches off origin/HEAD onto a new branch worktree-feature-auth and starts the session in that directory. You can edit code as if it were a normal checkout. The session is completely isolated from your main checkout.

If you leave the name out (claude --worktree without an argument), Claude generates a random name like bright-running-fox. Handy for quick experiments, unhandy when you want to find that worktree again tomorrow. My advice: always give it a name.

5. Open a second worktree in parallel

Second terminal, same repo path, different name:

claude --worktree bugfix-123

Now two sessions are running in parallel. Both have their own subset of files, both write to their own branch, they do not get in each other's way. If you change a file in session 1 and open the same file in session 2, session 2 shows you the unchanged state of that file from the branch base. That was exactly the point.

6. .worktreeinclude for .env files

By default a worktree is a fresh checkout, so all gitignored files are missing. Your .env, .env.local, local configs, secrets, all gone. The result is that your app does not start inside the worktree because no DB URL is set.

Solution: create a file .worktreeinclude in the repo root, same syntax as .gitignore. Example:

.env
.env.local
config/secrets.json

These files get copied into the new worktree on every --worktree call, provided they are gitignored (tracked files are never duplicated). My tip: write the .worktreeinclude right away during your first worktree setup, otherwise in 4 weeks you will have the problem that your new worktree starts without .env and it takes you 20 minutes to work out why.

7. Turn on subagent isolation

If your session spawns subagents (one subagent for tests, one for lint, one for docs), those subagents running in parallel can write into your files and overwrite each other. Solution: let subagents run in worktrees of their own.

Option A (per session): say "use worktrees for your agents" in the session. Claude puts every subagent into a temporary worktree.

Option B (permanent, for a custom subagent): add this to the frontmatter of the subagent file:

---
name: test-runner
isolation: worktree
---

Subagent worktrees are removed automatically when the subagent finishes without changes. If a subagent has uncommitted changes, Claude asks you during cleanup.

We have also explained the subagent pattern in a playbook of its own: Your first sub-agent in 30 minutes.

8. Configure the base branch

By default worktrees branch off origin/HEAD, so off remote main. That is clean, you always start from the last pushed state. Sometimes though you want to branch off your local HEAD, for instance when you are sitting on a feature branch and want to isolate a subagent on top of it. Set this in ~/.claude/settings.json or in the project:

{
  "worktree": {
    "baseRef": "head"
  }
}

Only "fresh" (default, from origin/HEAD) and "head" (from local HEAD) are allowed. You cannot pass an arbitrary git ref. If you need that, use a manual git worktree add (step 10).

9. Open a worktree for a PR

I only discovered this last week and I think it is brilliant. You want to review a pull request, reproduce code or adjust it:

claude --worktree "#1234"

Claude fetches pull/1234/head from origin and puts the worktree under .claude/worktrees/pr-1234. You can also pass the full GitHub PR URL. Saves you the manual git fetch + worktree add + checkout fiddling.

Pairs well with our Pull request reviews with Claude Code playbook.

10. Cleanup and manual management

If you end the session cleanly and made no changes, Claude clears away the worktree and the branch automatically. If there are changes or commits, Claude asks: keep the worktree (default) or delete it.

In non-interactive runs (claude -p without a terminal) nothing gets cleaned up, because no prompt is possible. There you have to do it yourself:

git worktree list
# zeigt alle aktiven Worktrees
git worktree remove .claude/worktrees/feature-auth
# entfernt einen

The manual variant without the --worktree flag, for when you want full control over path and branch:

git worktree add ../mein-projekt-feature-a -b feature-a
cd ../mein-projekt-feature-a
claude

Do not forget: every worktree is a fresh checkout, so you need a one-off npm install, pnpm install, python -m venv or whatever your setup requires. I wrote myself a small shell script for that which runs pnpm install automatically after the worktree is created, saving 2 minutes per worktree.

What comes next

Once you have the worktree workflow down, the jump to real parallel agent teams is worth it. That gets interesting when you are not only isolating files but also need coordination between several Claude sessions. Our playbook Your first sub-agent in 30 minutes is the way in, after that Hooks against hallucinations is the worthwhile next step for securing the worktree lifecycle.

If you have never done anything with the git worktree command, we also have a gentle introduction to git for AI workflows: Git for AI, 30-minute quickstart.

Source

Official Anthropic docs: https://code.claude.com/docs/en/worktrees (as of 2026-05-22). Settings reference for worktree.baseRef: https://code.claude.com/docs/en/settings. Manual worktree management via git: https://git-scm.com/docs/git-worktree.