Claude Code worktrees: run parallel sessions without collisions

Last updated: November 8, 2026

TL;DR

Claude Code worktrees give each session its own checkout of your repository, so two sessions can edit the same project without overwriting each other. Run claude -w <name> and Claude Code creates a git worktree under .claude/worktrees/<name>/ on a new branch called worktree-<name>, then starts the session inside it.

• 🧰 Before you start. You need a git repository you've opened in Claude Code once, plus one line in .gitignore.
• 🌳 Start it. claude -w <name> in one terminal, a different name in the next.
• 🔑 Bring your secrets. A .worktreeinclude file copies .env and other gitignored files into every new worktree.
• 🧹 Finish. Exit, and Claude Code removes a clean worktree or asks you about one with work in it.
• 🔀 Branch from somewhere else. Your current work with worktree.baseRef, or a pull request with claude -w "#1234".
• 🤖 Isolate subagents. Add isolation: worktree to a custom subagent.
• 🩹 Fix the errors. Most failures name their cause, and the table below matches each to its fix.

Before you start

You need three things, all from Anthropic's worktrees guide:

1. A git repository. Worktrees need git. In a folder with no version control, run git init and make a first commit. Other version control systems need a hook, covered under the errors below.
2. Workspace trust. If you've never run Claude Code in the repository, run claude there once and accept the trust dialog. Otherwise the worktree command exits with an error. Non-interactive runs with -p skip this check.
3. A .gitignore entry. Add .claude/worktrees/ so worktree contents don't show up as untracked files in your main checkout.

Step 1: Start a session in a worktree

Pass -w with a name. Claude Code creates the worktree and starts the session in it:

claude -w feature-auth

The worktree lands at .claude/worktrees/feature-auth/ in your repository root, on a new branch named worktree-feature-auth. Run the command again in a second terminal with a different name, and that session gets its own isolated checkout. Leave the name off and Claude Code picks one, such as bright-running-fox.

You can also start in your normal checkout and ask Claude to "work in a worktree" partway through. It creates one with its EnterWorktree tool. Claude Code asks for your approval first if Claude tries to enter a path outside .claude/worktrees/, because the move takes the session's write access and project configuration with it.

If you run several sessions from one Claude Code remote control server, pressing w in the server's terminal gives each new session its own worktree in the same way.

Step 2: Set up the worktree's environment

A worktree is a fresh checkout, so it has your tracked files and nothing else. Install dependencies in it, either by asking Claude or by running your project's setup yourself in the worktree directory.

To copy gitignored files such as .env into every new worktree automatically, add a .worktreeinclude file to your project root. It uses .gitignore syntax:

.env
.env.local
config/secrets.json

Only files that match a pattern and are also gitignored get copied, so tracked files are never duplicated. The file applies to every worktree Claude Code creates with git: -w sessions, subagent worktrees and parallel sessions in the desktop app.

One pattern trips people up. If the files you want sit inside a directory that's gitignored as a whole, a pattern starting with **/ only reaches them when the first name after **/ is part of that directory's path. Name the directory in the pattern instead: write vendor/**/config.json, not **/config.json.

Step 3: Finish and clean up

When you exit an interactive worktree session, Claude Code checks the worktree for work that removing it would delete, then acts on what it finds:

Commit or push before you answer "remove". Keeping preserves the directory and branch, and Claude Code prints the command to come back to them.

Come back to a worktree later

Resume with the command Claude Code prints when you exit and keep the worktree. It pairs the worktree flag and name with the resume flag (-w and -r in their short forms), so copy it as printed.

A session that ended inside a worktree without exiting it goes back to that worktree when you resume it. If the worktree directory has been deleted since, the session resumes where you launched Claude Code and tells you the worktree is gone.

Passing a name that already exists opens that worktree instead of creating a new one. By default, a reopened worktree starts fresh from your default branch when it has no uncommitted changes, is still on its own branch, and either has no commits of its own or its pull request was merged and the remote branch deleted. Otherwise it reopens at its old tip.

Branch from your current work or a pull request

New worktrees branch from your repository's default branch on the remote, usually main, so each one starts from a clean tree. Two settings change that.

Branch from your current work. Set worktree.baseRef to "head" in your settings, and new worktrees carry your unpushed commits and feature-branch state:

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

The setting takes only "fresh", the default, or "head". It doesn't accept a branch name, so to start from a specific existing branch, create the worktree with git yourself, as shown under the manual commands below.

Branch from a pull request. Pass the pull request number with a #, a GitHub pull request URL, or a GitLab merge request URL. Quote it, or your shell reads # as the start of a comment:

claude -w "#1234"

Claude Code fetches that change's head commit from your origin remote and creates the worktree at .claude/worktrees/pr-1234. The fetch never waits for a password or passphrase. If git would ask for one, the fetch fails, so load your SSH key into ssh-agent first.

Give subagents their own worktrees

Subagents can run in their own worktrees so their parallel edits don't conflict. Ask Claude to "use worktrees for your agents", or make it permanent for a custom subagent with isolation: worktree in the frontmatter of its file in .claude/agents/. A refactoring subagent's frontmatter, for example, carries name: refactorer, a one-line description of when to use it, and isolation: worktree.

Three behaviors are worth knowing before you rely on it:

• Cleanup. Each subagent gets a temporary worktree that Claude Code removes when the subagent finishes without changes. A worktree with changes stays on disk.
• Base branch. Subagent worktrees branch from the same base as -w, so they start from your default branch unless worktree.baseRef is "head". Set it to "head" when subagents need your in-progress work.
• Instructions. A subagent in a worktree takes its instruction files from your main conversation. In the default location, it doesn't load the CLAUDE.md or .claude/rules/ at the worktree's root, even if they differ on that branch. Our guide to AGENTS.md vs CLAUDE.md covers which file Claude Code reads and when.

Choosing between subagents, agent view and agent teams in the first place is covered in our guide to how to run Claude Code agents in parallel.

What a worktree shares with your main checkout

A worktree gets its own files and branch. These four things it shares with your main checkout, whether Claude Code or git worktree add created it:

Hooks are the exception to watch. After Claude enters a worktree, ${CLAUDE_PROJECT_DIR} in your hook commands still points at the project root where the session started. A hook that needs the worktree's path should read the cwd field from its input instead.

Clean up the Claude Code worktrees that stay behind

Some worktrees outlive their session, and you remove them with git.

• Non-interactive runs with -p have no exit prompt, so Claude Code doesn't clean up their worktrees.
• Subagent and background-session worktrees go in a periodic sweep once they're older than your cleanupPeriodDays setting. The sweep skips any worktree that still holds changed or untracked files or unpushed commits, and any worktree you created yourself with git worktree add.
• Locked worktrees. Claude Code holds a git worktree lock while an agent runs in one, and the sweep releases locks left by sessions whose process has exited.

To remove one by hand:

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

Add -f to git worktree remove if the worktree has uncommitted changes or untracked files. If git refuses because the worktree is locked, release the lock first with the matching git worktree subcommand, listed in the git worktree docs.

To create a worktree yourself, on an existing branch or outside the repository, use git directly and start Claude Code inside it:

git worktree add ../project-bugfix fix-issue-456
cd ../project-bugfix
claude

Common Claude Code worktree errors and fixes

Most worktree errors name their cause. Match the message or symptom:

For SVN, Perforce or Mercurial, a WorktreeCreate hook replaces the git logic entirely and a WorktreeRemove hook cleans up. With a hook in place, .worktreeinclude isn't processed, so copy local config files inside the hook script.

Frequently asked questions

What is a Claude Code worktree?

A Claude Code worktree is a git worktree that a Claude Code session runs in: a separate working directory with its own files and branch that shares your repository's history and remote. Each session edits its own copy, so one can build a feature while another fixes a bug in the same repository.

How do I start Claude Code in a worktree?

Run claude -w <name> in your repository. Claude Code creates the worktree under .claude/worktrees/<name>/ on a new branch called worktree-<name> and starts the session there. Leave the name off and it generates one. You can also ask Claude to "work in a worktree" mid-session.

Where does Claude Code put worktrees?

Under .claude/worktrees/<name>/ at your repository root, on a branch named worktree-<name>. A pull request worktree goes in .claude/worktrees/pr-<number>. Add .claude/worktrees/ to your .gitignore. To put worktrees somewhere else, use git worktree add yourself or a WorktreeCreate hook.

How do I copy my .env file into a Claude Code worktree?

Add a .worktreeinclude file to your project root that lists .env and any other files to copy, in .gitignore syntax. Claude Code copies files that match a pattern and are gitignored into every worktree it creates with git. A WorktreeCreate hook has to copy them itself.

Does Claude Code delete worktrees automatically?

Partly. On exit, a clean worktree from an unnamed session is removed with its branch, and anything with work in it prompts you. Clean subagent worktrees are removed when the subagent finishes. Worktrees from -p runs stay until you run git worktree remove.

Can Claude Code subagents use worktrees?

Yes. Ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter. Each subagent gets a temporary worktree that's removed if it finishes without changes. Subagent worktrees branch from your default branch unless worktree.baseRef is set to "head".

Can I start a Claude Code worktree from a pull request?

Yes. Pass the number with a #, a GitHub pull request URL, or a GitLab merge request URL, in quotes: claude -w "#1234". Claude Code fetches that change from origin and creates the worktree at .claude/worktrees/pr-1234.

Do worktrees stop Claude from editing my main checkout?

Mostly. Inside a worktree, Claude Code blocks file edits aimed at the main checkout, commands that run there, and git redirected into it. Those checks read paths and command text, so a plain cp or shell redirect into the main checkout isn't caught. Your permission and sandbox settings still apply.

Make every worktree start smart

A new worktree starts with your repository's files and none of the context in your head. The more of your project's rules live in the repo, the less each parallel session has to be told. Our guide to compound engineering for Claude Code shows how to build those rules up one fix at a time, so every worktree session inherits them.