Claude Code Worktrees Guide: Run Parallel Sessions Without Conflicts (2026)

What Are Git Worktrees and Why Do They Matter for Claude Code?

Git worktrees create separate working directories that share the same repository history and remote connections. Each worktree has its own files and branch. According to incident.io's engineering team, they routinely run 4-5 parallel Claude agents using worktrees with zero file conflicts.

Without worktrees, two Claude sessions editing the same repo will clobber each other's changes. Stashing and branch-switching breaks AI agent context. Worktrees eliminate the problem entirely.

WITHOUT

Single working directory

Two Claude sessions edit the same files. Changes collide. Branch switches wipe context. One agent's work blocks another.

WITH

Worktree isolation

Each Claude session gets its own directory and branch. Full isolation. Shared history. No conflicts.

Quick Start: Your First Claude Code Worktree

Claude Code v2.1.49 (shipped February 19, 2026) added native worktree support via the --worktree flag. One command creates an isolated directory, a new branch, and starts Claude inside it.

Named worktree

claude --worktree feature-auth

Auto-named worktree

claude --worktree

Generates a random name like "bright-running-fox"

Short flag

claude -w bugfix-123

Where worktrees live

Worktrees are created at <repo>/.claude/worktrees/<name> and branch from origin/HEAD. The branch is named worktree-<name>.

Running Parallel Claude Code Sessions

The core workflow: open multiple terminal windows, each running Claude in its own worktree. You can have Claude building a feature in one worktree while fixing a bug in another -- zero interference between sessions.

Terminal 1 -- Feature work

claude --worktree feature-auth
# "Add OAuth2 login flow with Google provider"

Terminal 2 -- Bug fix

claude --worktree bugfix-payment-race
# "Fix the race condition in checkout flow"

Terminal 3 -- Test coverage

claude --worktree add-tests
# "Add integration tests for the payment module"

Each session operates on its own copy of the codebase. When one finishes, push its branch and create a PR -- same as any git workflow.

Handling .env Files with .worktreeinclude

Git worktrees are fresh checkouts. They do not include gitignored files like .env. If your app needs environment variables to run, your worktree sessions will break immediately without this step.

Create a .worktreeinclude file in your project root. It uses .gitignore syntax. Only files that match a pattern AND are also gitignored get copied to new worktrees.

.worktreeinclude

.env
.env.local
config/secrets.json
*.pem

Add .claude/worktrees/ to .gitignore

Worktree contents appear as untracked files in your main repo without this. Add .claude/worktrees/ to your .gitignore to keep things clean.

Fixing the Base Branch (origin/HEAD)

Worktrees branch from origin/HEAD. Git sets this reference once when you clone. If the repository's default branch changed on GitHub since then, your worktrees will branch from the wrong base.

Re-sync with remote default

git remote set-head origin -a

Set a specific base branch

git remote set-head origin develop

For full control over how worktrees are created -- including choosing a different base per invocation -- configure a WorktreeCreate hook. The hook replaces Claude Code's default git worktree logic entirely.

Subagent Worktree Isolation

Subagents can also use worktree isolation to work in parallel without conflicts. This is where worktrees become a force multiplier -- a single Claude session can spawn multiple subagents, each in its own worktree, executing independent tasks concurrently.

Interactive method

Ask Claude to "use worktrees for your agents" during a session. Claude will spawn each subagent in its own isolated worktree automatically.

Frontmatter method

Add isolation: worktree to your custom subagent's frontmatter in .claude/agents/.

Custom subagent with worktree isolation (.claude/agents/feature-builder.md)

---
name: feature-builder
description: Builds features in isolation
isolation: worktree
---

Build the requested feature. Write tests.
Run the test suite before finishing.

Subagent worktrees are cleaned up automatically when the subagent finishes without changes. Orphaned worktrees from crashes are removed at startup after the cleanupPeriodDays threshold, provided they have no uncommitted changes, untracked files, or unpushed commits.

Worktree Cleanup and Lifecycle

Claude Code handles worktree cleanup automatically when you exit a session. The behavior depends on whether you made changes.

NO CHANGES

Auto-removed

Worktree directory and branch are deleted automatically. No action required.

CHANGES EXIST

Prompted

Claude asks if you want to keep or remove the worktree. Keeping preserves your directory and branch. Removing deletes everything -- including uncommitted work.

ORPHANED

Auto-cleaned at startup

Subagent worktrees left by crashes are removed at next startup if older than cleanupPeriodDays, with no uncommitted changes or unpushed commits.

Manual cleanup

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

Real-World Workflow: Feature + Hotfix in Parallel

Here is the workflow we use daily at KaiShips. One Claude session builds a feature while another patches a production bug -- both running simultaneously with zero context switching.

Start the feature session

claude -w new-dashboard -n dashboard-build

The -n flag names the session so you can resume it later with claude --resume dashboard-build.

Bug report arrives -- start a hotfix session

claude -w hotfix-checkout-crash

Opens in a new terminal. The feature session keeps running undisturbed in its own worktree.

Hotfix done -- push and merge

# Inside the hotfix worktree session:
"Push this branch and create a PR"

Exit the session. Claude cleans up the worktree after you choose to remove it.

Back to the feature -- resume by name

claude --resume dashboard-build

Full context restored. No re-explaining what you were building.

Dependencies and Environment Setup

Each worktree is a fresh checkout. Your node_modules or virtual environment won't exist until you install. Tell Claude to run the setup as the first step, or configure it in your CLAUDE.md.

Node.js / npm

npm install

Python / venv

python -m venv .venv
pip install -r requirements.txt

Go modules

go mod download

Ruby / Bundler

bundle install

Pro tip: automate setup in CLAUDE.md

Add a "Setup" section to your CLAUDE.md with the exact commands to initialize a fresh checkout. Claude reads this file automatically and can run the setup without you having to specify it each time.

Advanced: WorktreeCreate and WorktreeRemove Hooks

For teams needing custom worktree behavior -- running setup scripts, fetching from specific refs, or integrating with non-git VCS -- Claude Code provides WorktreeCreate and WorktreeRemove hooks in settings.json.

settings.json -- auto-install deps on worktree creation

{
"hooks": {
"WorktreeCreate": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "npm install"
}]
}]
}
}

The WorktreeCreate hook replaces Claude Code's default git worktree logic entirely. This means .worktreeinclude is not processed when a custom hook is configured -- copy any config files inside your hook script instead.

5 Mistakes That Break Claude Code Worktree Workflows

We learned these the hard way. Save yourself the debugging time.

Forgetting .worktreeinclude

Your app crashes on boot because .env is missing. Create a .worktreeinclude file listing every gitignored config file your app needs.

Stale origin/HEAD

Worktrees branch from the wrong base because your local origin/HEAD is outdated. Run git remote set-head origin -a to re-sync.

Skipping dependency installation

Worktrees are fresh checkouts with no node_modules. Claude will hit import errors until you run npm install. Automate this with a WorktreeCreate hook.

Not adding .claude/worktrees/ to .gitignore

Your git status fills with hundreds of untracked files from worktree directories. Add the path to .gitignore before creating your first worktree.

Stale index.lock from crashed agents

If a Claude process crashes while holding a git lock, a stale .git/index.lock file blocks all git operations. Delete it manually to unblock.

Claude Code Worktree Command Reference

Every worktree command you need in one place.

Command	What it does
claude --worktree name	Create named worktree and start Claude in it
claude -w name	Short form of --worktree
claude --worktree	Auto-generate a random worktree name
git worktree list	List all active worktrees
git worktree remove path	Manually remove a worktree
git remote set-head origin -a	Re-sync origin/HEAD with remote default

The complete playbook

Get every config, workflow, and the reasoning behind each decision in the full KaiShips Guide to Claude Code.

This post covers worktrees. The guide covers CLAUDE.md setup, memory architecture, hooks, subagents, cron automation, and 5 more chapters of production-tested configs.

Get the KaiShips Guide to Claude Code -- $29

Frequently Asked Questions

What are Claude Code worktrees?

Claude Code worktrees are isolated working directories created with the --worktree (-w) flag. Each worktree gets its own branch and file state, so multiple Claude sessions can edit code in the same repository without conflicts. Worktrees are stored at <repo>/.claude/worktrees/<name> and branch from origin/HEAD.

How many parallel Claude Code worktrees can I run?

There is no hard limit on worktree count. Incident.io routinely runs 4-5 parallel Claude agents using worktrees. The practical limit depends on your machine's CPU, RAM, and API rate limits. Most developers find 3-5 concurrent worktrees optimal for balancing throughput and resource usage.

Do worktrees copy my .env files automatically?

No. Git worktrees are fresh checkouts that exclude gitignored files like .env or .env.local. To copy these files automatically, create a .worktreeinclude file in your project root listing the patterns to copy. Only files that match a pattern AND are gitignored get copied.

What happens when I exit a Claude Code worktree session?

Claude handles cleanup based on your changes. If you made no changes, the worktree and its branch are removed automatically. If changes or commits exist, Claude prompts you to keep or remove the worktree. Keeping it preserves the directory and branch. Removing it deletes everything including uncommitted changes.

Can Claude Code subagents use worktrees?

Yes. Add isolation: worktree to a custom subagent's frontmatter, or ask Claude to 'use worktrees for your agents' during a session. Each subagent gets its own worktree that is automatically cleaned up when it finishes without changes. Orphaned subagent worktrees are removed at startup after the cleanupPeriodDays threshold.