Run parallel Claude Code sessions without them stepping on each other
The --worktree flag gives each session its own checkout and branch. The setup details are where people get caught.
Two Claude Code sessions in the same checkout will eventually edit the same file. Git worktrees are the standard answer: each session gets its own working directory and branch, backed by the same repository history. Claude Code has a flag for it, and the worktree docs cover more edge cases than the one-liner suggests.
Start one
claude --worktree feature-auth
-w works too. By default the worktree lands in .claude/worktrees/feature-auth/ at your repo root, on a new branch called worktree-feature-auth. Run the command again with another name in a second terminal and you have two isolated sessions. Skip the name and Claude invents one, like bright-running-fox.
Add .claude/worktrees/ to your .gitignore, or the contents show up as untracked files in your main checkout.
Three things a fresh checkout doesn’t have
A worktree starts clean, so it’s missing everything git doesn’t track.
Dependencies. Ask Claude to run your install step, or do it yourself in the worktree directory. Nothing carries over from the main checkout’s node_modules or virtualenv.
Local config. Your .env isn’t there either. Add a .worktreeinclude file at the project root, in .gitignore syntax, listing the ignored files to copy into every new worktree:
.env
.env.local
config/secrets.json
Only files that match a pattern and are gitignored get copied, so tracked files are never duplicated.
The right starting point. New worktrees branch from the repository’s default branch on the remote, not from whatever you have checked out. If you want a worktree to carry your unpushed commits, set worktree.baseRef to "head" in settings. Branching from a pull request is a one-liner, and the quotes matter so your shell doesn’t read # as a comment:
claude --worktree "#1234"
Subagents can get their own worktree
If a subagent edits files in parallel with others, give it isolation in its frontmatter. This example is from the docs:
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor across every affected file, then run the tests
and report the results.
Each run gets a temporary worktree, removed automatically if the subagent finishes without changes. One catch from the docs: a subagent in its own worktree takes its starting instructions from your main conversation, and doesn’t load the CLAUDE.md at the worktree’s root, even if that file differs on the worktree’s branch.
Cleanup
When you exit an interactive session, Claude checks the worktree for uncommitted files and new commits. A clean, unnamed worktree is removed along with its branch. A named one asks first. If there’s work in it, you choose between keeping and removing, and removing deletes the branch too.
Non-interactive runs with -p don’t get an exit prompt, so they leave their worktrees behind. Remove them with git worktree remove, and if git refuses because of a lock, run git worktree unlock first.
Isolation and permissions
While a session is in a worktree, Claude Code blocks edits to paths in the main checkout, and blocks commands that point git back at it. That’s a safety net against an agent wandering out of its sandbox. It also means a clever one-liner with computed command names may get refused, and the error tells Claude how to rewrite it.
Approvals are shared. If you pick “Yes, and don’t ask again” for a Bash command inside a worktree, the rule is saved to the main checkout’s .claude/settings.local.json, so it applies everywhere in that repo, including after the worktree is gone. Worth knowing before you click it.
Next step: open two terminals, start two named worktrees on unrelated tasks, and see how often you’d have collided in one checkout.