Claude Code Worktrees: Run Parallel Sessions Safely

One Claude Code session at a time wastes most of your waiting time. Two sessions in the same checkout is worse: they overwrite each other’s edits and break each other’s test runs. Git worktrees fix that by giving each session its own directory and branch on top of one shared repository, and Claude Code now creates and cleans them up for you.

Everything below is checked against the official worktrees docs as of October 2026. Worktree behaviour has changed across recent versions, so update Claude Code (claude update) if a flag below isn’t recognised.

Worktrees in 60 seconds

A git worktree is an extra working directory attached to the same .git data. Each worktree has its own branch and files; commits made in one are immediately visible to the others because they share history.

	Separate clone	Worktree
Disk use	Full copy of history	Shares .git
Branch sharing	Push and fetch between clones	Instant, same repo
Same branch twice	Possible	Not allowed (git refuses)
Setup	git clone	git worktree add or claude --worktree

The fast path: claude --worktree

# terminal 1
claude --worktree feature-auth

# terminal 2
claude --worktree fix-flaky-tests

Each command creates <repo>/.claude/worktrees/<name>/ on a new branch named worktree-<name>, then starts the session inside it. -w is the short form. Leave the name out and Claude picks one for you.

Details worth knowing:

• The repo needs at least one commit, otherwise you’ll see Failed to resolve base branch "HEAD".
• Base branch: by default the worktree starts from a fresh origin/<default-branch>, not your current HEAD. Set worktree.baseRef to "head" in settings if you want your current branch instead.
• Reuse: running claude --worktree feature-auth again reopens that worktree rather than creating a new one.
• From a PR: claude --worktree "#1234" or a GitHub PR / GitLab MR URL creates .claude/worktrees/pr-1234 for reviewing or finishing someone’s branch.
• tmux: claude -w feature-auth --tmux opens the session in a tmux pane.

Add the folder to .gitignore as the docs recommend:

echo ".claude/worktrees/" >> .gitignore

You can also ask mid-session: “work on this in a worktree”. Claude uses its EnterWorktree and ExitWorktree tools to move the session.

Copy the files git doesn’t track: .worktreeinclude

A new worktree has everything committed and nothing else, so .env and local config are missing and your dev server won’t start. Create .worktreeinclude at the project root, using .gitignore syntax:

.env
.env.local
config/secrets.json

Claude Code copies files that match a pattern and are gitignored into each new worktree. It applies to --worktree, subagent worktrees and the desktop app. Keep the list short: you’re copying secrets into more places, and every worktree session can read them unless your permission rules deny it.

Heavy directories

Reinstalling node_modules in every worktree is slow. Two settings help:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/api", "packages/shared"]
  }
}

symlinkDirectories links directories from the main checkout instead of copying them, and sparsePaths checks out only the paths you list, useful in big monorepos. Symlinked dependencies are shared, so don’t run installs that change them from two worktrees at once.

Cleanup rules

Situation	What happens
Interactive session, unnamed, no changes	Worktree and branch removed on exit
Named session, or worktree has changes or commits	Claude asks whether to keep or remove it
claude -p --worktree (headless)	No cleanup; remove it yourself
Subagent or background worktrees	Swept periodically once older than cleanupPeriodDays, unless they have unfinished work

To come back to a kept worktree: claude --worktree <name> --resume. To remove one by hand:

git worktree list
git worktree remove .claude/worktrees/feature-auth
git branch -d worktree-feature-auth

Subagents in their own worktree

Any subagent can be isolated by adding one line to its frontmatter:

---
name: migration-writer
description: Writes and tests database migrations. Use for schema changes.
isolation: worktree
---

The subagent works in a temporary worktree, which is removed automatically if it made no changes. Like --worktree, it branches from the default branch rather than the parent session’s HEAD, so commit or push anything the subagent needs to see first.

/batch: worktrees at scale

The bundled /batch <instruction> skill splits a large change into roughly 5 to 30 independent units, shows you the plan, then runs each unit as a background subagent in its own worktree. Each one runs tests and publishes its change. It’s built for mechanical, parallelisable work such as “migrate every API route to the new error helper”. Our slash commands cheatsheet lists the related /tasks command for watching progress.

Manual worktrees still work

Use plain git when you want a worktree outside the repo or on an existing branch:

git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix fix-issue-456
cd ../project-feature-a && claude

Claude Code treats it like any checkout. You lose .worktreeinclude copying and automatic cleanup, so handle .env and removal yourself.

What worktrees share

All worktrees share the .git directory, so commits, branches and stashes are common. Claude Code also shares a few things with the main checkout:

• plugins installed at project scope;
• “don’t ask again” permission approvals, saved in the main checkout’s .claude/settings.local.json;
• untracked skills, agents and commands, read through from the main checkout.

Committed files such as CLAUDE.md and .claude/settings.json come from the branch itself. If you change your CLAUDE.md in one worktree, other sessions see it only after they merge or rebase.

Custom worktree creation with hooks

If you don’t use git, or need a custom layout, the WorktreeCreate and WorktreeRemove hooks replace the built-in logic. WorktreeCreate receives the name on stdin and must print the worktree path on the last line of stdout. Note that hooks don’t fire when Claude runs git worktree add itself through Bash.

Desktop app

In the Claude Code desktop app, start sessions with + New and turn on the Worktree toggle before you start (it’s off by default). Split view shows two sessions side by side. Worktree location and branch prefix are in Settings under Claude Code. The docs warn that archived sessions with uncommitted worktree changes are deleted after about 30 days, so commit before archiving.

A practical parallel workflow

1. Keep one “main” session for planning and review.
2. Spin up one worktree per independent task: claude -w <task>.
3. Give each a clear, self-contained prompt and a way to verify (tests).
4. Review each branch’s diff, then merge or open a PR.
5. Watch your usage: every parallel session draws on the same plan limits. Our pricing and limits guide and ccusage help keep that visible.

Parallel sessions also make cross-tool setups easy: run Claude Code in one worktree and another agent in the next, as described in Claude Code vs Codex.

Worktrees in your Claude kit

Worktrees are the workflow glue of a Claude kit: commit a .worktreeinclude, the .gitignore entry and any worktree settings to the repo so every teammate gets the same isolated setup on day one.