Claude Code worktrees: run parallel sessions safely
Run parallel Claude Code sessions with git worktrees: claude -w, where worktrees live, .worktreeinclude, subagent isolation, cleanup, and what they share.
Two Claude Code sessions in one checkout is a race. One is refactoring the auth module while the other fixes a bug in the same file, and whichever writes last wins. Git worktrees fix that: each session gets its own working directory and branch, sharing the same repository history.
This guide covers the worktree workflow in Claude Code, from Anthropic's worktrees documentation, checked on 16 November 2026.
Start a session in a worktree
claude --worktree feature-auth
Or the short form, claude -w feature-auth. Claude Code creates a worktree at .claude/worktrees/feature-auth/ on a new branch, worktree-feature-auth, and starts the session there. Run the same command with another name in a second terminal for a second isolated session. Leave out the name and Claude picks one.
Two setup steps:
- Ignore the folder. Add
.claude/worktrees/to.gitignore, so worktree contents don't appear as untracked files in your main checkout. - Trust the directory once. Interactive worktree sessions need workspace trust, so run
claudeonce in the repository first if you never have.
You can also ask Claude mid-session to "work in a worktree," and it creates one for you.
Set up the environment
A worktree is a fresh checkout. Gitignored files like .env aren't there and dependencies aren't installed. Two fixes:
Copy small gitignored files with a .worktreeinclude at the project root. It uses .gitignore syntax, and only files that match and are gitignored get copied:
.env
.env.local
config/dev-credentials.json
Install dependencies by putting the install command in CLAUDE.md, so Claude runs it when it starts in a new checkout. Don't put node_modules in .worktreeinclude: it copies rather than links, which means a full copy per worktree. For large directories, Anthropic's best practices point to the worktree.symlinkDirectories setting.
Choose what the worktree branches from
New worktrees branch from your repository's default branch on the remote, so they start clean. To carry your current, unpushed work into new worktrees instead, set worktree.baseRef to "head" in settings:
{
"worktree": {
"baseRef": "head"
}
}
To start from a pull request, pass its number or URL:
claude --worktree "#1234"
Claude Code fetches that pull request's head commit from origin and creates .claude/worktrees/pr-1234.
Give subagents their own worktrees
Subagents can work in separate worktrees, so parallel edits don't collide. Ask Claude to use worktrees for its agents, or make it permanent for a custom subagent:
---
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 subagent gets a temporary worktree, removed automatically when it finishes without changes. More on subagents in Claude Code subagents: 5 examples.
How isolation is enforced
While a session is in a worktree, Claude Code blocks tool calls that would reach into the main checkout:
- File edits that target a path in the main checkout.
- Commands whose working directory is the main checkout.
- Git commands redirected into the main checkout, through
git -C,--git-dir, or similar. - Commands whose git usage it can't verify from the command text.
These checks read paths, directories, and command text. They don't track every file a shell command writes, so a cp into the main checkout falls under your normal permission and sandbox settings instead.
What worktrees share
A worktree has its own files and branch, but some things carry across:
| Shared | Detail |
|---|---|
| Git history | Worktrees use the main repository's .git directory |
| Project plugins | Installed at project scope in the main checkout, they load in worktrees too |
| Permission approvals | "Don't ask again" in a worktree saves to the main checkout's settings |
| Untracked skills and agents | If the worktree has no .claude/skills, the main checkout's load instead |
| Auto memory | All worktrees of one repository share one auto memory directory |
Cleanup
When you exit an interactive worktree session:
- A clean, unnamed worktree is removed automatically, along with its branch.
- A worktree with changes or new commits prompts you to keep or remove it. Keep it, and Claude Code prints the command to resume later.
- A named session's worktree prompts you first.
Worktrees from claude -p runs have no exit prompt, so remove them yourself with git worktree remove, unlocking first with git worktree unlock if needed.
When parallel sessions still collide
Worktrees stop sessions from overwriting each other's files. They don't stop two sessions from making contradictory choices. One session renames an API field while another builds a client against the old name; both branches merge cleanly, and the product is broken. The fix is a decision both sessions see before they start, not a better merge.
Where Lockstep fits
Lockstep briefs every Claude Code session on the team's approved decisions at session start, so parallel sessions in different worktrees build against the same rules. Decisions are captured from PRDs, Slack, and pull requests, become binding when their owner approves them, and, when a session changes a shared API surface, Lockstep can route that change to the other services that depend on it. See two AI agents, one codebase.
Session briefings work with Claude Code today. See how it works.
Sources checked 16 November 2026
- https://code.claude.com/docs/en/worktrees
- https://code.claude.com/docs/en/best-practices
- https://code.claude.com/docs/en/memory
Related reading
For the practices around unattended and parallel runs, see Claude Code best practices. For agent teams versus subagents, see Claude Code subagents: 5 examples. For teams of coordinated sessions, see Claude Code agent teams. To pick a session back up later, see how to resume a Claude Code session. For repository layout and agents, see monorepo vs polyrepo.
Frequently asked questions
- How do I run Claude Code in a worktree?
- Run claude --worktree <name>, or claude -w <name>. Claude Code creates a worktree under .claude/worktrees/<name>/ at the repository root on a new branch named worktree-<name>, and starts the session there. Run it again with another name in a second terminal for a parallel session.
- Where does Claude Code put worktrees?
- Under .claude/worktrees/ at your repository root. Add .claude/worktrees/ to .gitignore so their contents don't show as untracked files in your main checkout.
- How do I get my .env file into a Claude Code worktree?
- Add a .worktreeinclude file to the project root, using .gitignore syntax, listing files like .env and .env.local. Claude Code copies matching gitignored files into each worktree it creates. Keep it to small files, because it copies rather than links.
- Do Claude Code worktrees get cleaned up?
- When you exit an interactive worktree session, Claude Code removes a clean, unnamed worktree and its branch automatically, and asks before removing one that has changes or belongs to a named session. Worktrees from claude -p runs aren't cleaned up; remove them with git worktree remove.
- Can subagents use worktrees?
- Yes. Ask Claude to use worktrees for its agents, or add isolation: worktree to a custom subagent's frontmatter. Each subagent gets a temporary worktree that is removed when it finishes without changes.
Keep reading