Claude Code worktrees: run parallel sessions without collisions

What is a git worktree, and why use one with Claude Code?

A git worktree is a separate working directory with its own files and its own branch. It shares the repository history and remote with your main checkout, so it is not a second clone. The Claude Code worktrees page states the reason to combine them: each session gets a separate copy of the files to edit, so one session can build a feature while a second fixes a bug.

Without a worktree, two Claude sessions in one folder edit the same files, run the same dev server and fight over the same branch. With one, each session has its own folder and branch, and you decide later what to merge. The docs place worktrees among several ways to run Claude in parallel. They isolate file edits. Subagents split work inside one session (see the subagents guide), and cross-session messaging lets Claude pass findings between the sessions in your worktrees.

How do you start Claude in a worktree?

Pass --worktree, or -w, with a name. By default Claude Code creates the worktree under .claude/worktrees/<name>/ at your repository root, on a new branch named worktree-<name>, and starts Claude in it. If you leave the name off, Claude picks one such as bright-running-fox.

# Terminal 1: build a feature
cd my-app
claude --worktree feature-auth

# Terminal 2: fix a bug at the same time
cd my-app
claude --worktree fix-footer

# See every worktree git knows about
git worktree list

Four requirements and tips from the docs:

• The repository needs at least one commit. In a repository with no commits the command fails with Failed to resolve base branch "HEAD".
• It must be a git repository. Otherwise you see Can only use --worktree in a git repository. Run git init, make a first commit and retry.
• Accept the trust dialog first. Interactive runs require workspace trust. If you have never run Claude in the folder, run claude there once, then use --worktree. Runs with -p skip the check.
• Add .claude/worktrees/ to .gitignore so worktree contents do not show up as untracked files in your main checkout.

You can also ask for one mid-session. Tell Claude to work in a worktree and it uses its EnterWorktree tool. Add --tmux to claude -w feature-auth to also create a tmux session for the worktree (it uses iTerm2 native panes when available).

How do you set up .env files and dependencies in a new worktree?

A worktree is a fresh checkout. Gitignored files such as .env are not there, and dependencies are not installed. Two fixes cover it.

For files, add a .worktreeinclude file to your project root. It uses .gitignore syntax, and Claude Code copies files that match a pattern and are also gitignored into every worktree it creates. Tracked files are never duplicated.

.env
.env.local
config/secrets.json

Keep it to small files. It copies rather than links, so putting node_modules in it would mean a full copy per worktree. For large directories use the worktree.symlinkDirectories setting, which symlinks directories from the main repository into each worktree. For installs, either ask Claude to run your install command or keep the command in CLAUDE.md so Claude runs it whenever it starts in a new checkout.

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

Be careful with .env copies: they put secrets in another folder. If your project reads secrets from files, check your permission rules cover the worktree too (see the permissions guide).

What does a full parallel workflow look like, from start to merge?

Say you are building an app from an idea and want the login feature and a layout fix going at once. This is the sequence with exact commands. Git commands are standard; the Claude Code parts come from the docs.

1. Check your repository has a commit and is clean. Run git status and git log --oneline -1.
2. Start session one with claude --worktree add-login. Describe the feature and let Claude work. Ask it to install dependencies if needed.
3. Open a second terminal in the same repository and run claude --worktree fix-layout. Describe the fix.
4. Review each branch separately. From the main checkout, git diff main...worktree-add-login shows what session one changed. Run each app version to check it.
5. Push and open pull requests from each worktree, using the branch names worktree-add-login and worktree-fix-layout, for example git push -u origin worktree-add-login.
6. Exit each session. Claude checks the worktree for work removal would delete and asks what to do (next section).

Worktrees remove file collisions during the work. They do not remove merge conflicts afterward. If both branches touch the same lines, git still asks you to resolve them when you merge, so give each session a different part of the codebase where you can.

If you are still looking for something to build in parallel, the developer tools ideas on the board each come with a generated build prompt. Paste one into each session.

How do you clean up worktrees and resume them?

When you exit an interactive worktree session, Claude Code checks the worktree for changed or untracked files, uncommitted work inside checked-out submodules, and new commits.

To come back to a kept worktree, run the claude --worktree <name> --resume command that Claude Code prints on exit. Resuming a session that ended inside a worktree returns it to that worktree. If the directory no longer exists, Claude Code resumes in the folder you launched from and tells you the worktree is gone. Calling claude --worktree with a name that already exists opens the existing worktree rather than creating a new one.

Runs with -p have no exit prompt, so Claude does not clean up their worktrees. Remove those yourself:

# List worktrees
git worktree list

# Remove one (add --force if it has uncommitted changes)
git worktree remove .claude/worktrees/add-login

# If git says it is locked, pass --force twice (git's rule for locked worktrees)
git worktree remove --force --force .claude/worktrees/add-login

Worktrees created for subagents and background sessions are swept automatically once they are older than your cleanupPeriodDays setting and hold no work. The sweep leaves a worktree in place if it still has changed or untracked files or unpushed commits, or if you created it yourself with git worktree add.

Which branch does a worktree start from, and can it start from a pull request?

New worktrees branch from the repository's default branch on the remote, usually main. This is the worktree.baseRef setting with its default of fresh. Set it to head to branch from your current local HEAD instead, so the worktree carries your unpushed commits. You cannot set the value to a branch name. To start from a specific existing branch, create the worktree with git directly (see below).

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

To work on someone's pull request, pass the number with a hash, a GitHub pull request URL, or a GitLab merge request URL. Claude Code fetches the head commit from origin and creates the worktree at .claude/worktrees/pr-<number>. Quote the argument so your shell does not read the hash as a comment.

claude --worktree "#1234"

Can you create worktrees with plain git instead?

Yes. Do this when you need an existing branch checked out or want the worktree outside the repository. Then start Claude in the folder as usual.

# New worktree on a new branch
git worktree add ../project-feature-a -b feature-a

# Worktree from an existing branch
git worktree add ../project-bugfix fix-issue-456

# Start Claude inside it
cd ../project-feature-a
claude

# List and remove
git worktree list
git worktree remove ../project-feature-a

What do worktrees share with the main checkout?

• The .git directory. Commits made in a worktree land in the shared repository.
• Plugins installed at project scope load in every worktree of the repository.
• Permission approvals. Choosing “Yes, and don't ask again” for a Bash command in a worktree saves the rule to the main checkout's .claude/settings.local.json, so it applies in every worktree and outlives the worktree. On Windows and some other setups the rule stays with that worktree.
• Untracked skills, agents and commands. If the worktree has no .claude/skills folder of its own, Claude loads the main checkout's project skills.

While a session is isolated in a worktree, Claude Code also blocks four things: edits that target a path in the main checkout, commands whose working directory resolves to the main checkout, commands that redirect git into it, and commands whose shape it cannot verify stay inside the worktree. A plain cp or shell redirect that writes into the main checkout is not caught by these checks, so it falls under your normal permissions.

Can subagents run in their own worktrees?

Yes. Ask Claude to use worktrees for its agents, or set isolation: worktree in a custom subagent's frontmatter. Each subagent gets a temporary worktree that Claude Code removes when the subagent finishes without changes. This subagent file, from the docs, always runs in its own worktree:

---
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.

For one large mechanical change, the docs also mention /batch, which splits work into 5 to 30 units, shows you the plan, then runs each unit in its own worktree and opens a pull request for it. Subagent worktrees branch from the default branch unless worktree.baseRef is head.

What do the common worktree errors mean?

Worktree isolation uses git by default. For SVN, Perforce, Mercurial and others, you configure WorktreeCreate and WorktreeRemove hooks to supply your own creation and cleanup.