Claude Code Worktrees: Run Parallel Sessions Without Conflicts

The Problem: One Repo, Multiple Claude Sessions

You ask Claude to refactor authentication. While it works, you want to start a second session to fix a billing bug. Both sessions need to edit files in the same repo. If they touch the same file, you get conflicts. If they share a branch, you get a mess.

This is the most common friction point with AI coding agents. The agent is fast enough to work on multiple tasks, but the filesystem is a shared resource. Two sessions writing to the same directory is the same problem as two developers editing the same file on the same branch.

Git worktrees solve this. A worktree is a separate working directory with its own branch, sharing the same repository history. Claude Code has built-in support via one flag.

What Git Worktrees Are

A git worktree is a linked working directory attached to your repository. Unlike cloning the repo again, a worktree shares the same .git directory. This means all branches, tags, and remote connections are shared. But each worktree checks out a different branch and has its own file state.

# List existing worktrees
git worktree list

# Create a new worktree with a new branch
git worktree add ../my-feature -b feature-branch

# Create a worktree with an existing branch
git worktree add ../bugfix-dir bugfix-123

# Remove a worktree when done
git worktree remove ../my-feature

The --worktree (-w) Flag

Claude Code wraps git worktrees into a single flag. No manual directory management. No remembering to create branches first.

# Start Claude in a named worktree
claude --worktree feature-auth

# Shorthand
claude -w feature-auth

# Auto-generated name (e.g. "bright-running-fox")
claude --worktree

# Combine with a prompt
claude -w bugfix-123 "Fix the null pointer in payment handler"

When you run claude --worktree feature-auth, Claude does three things:

The worktree branches from the default remote branch (usually main or master). Claude sessions in a worktree see only the files in that worktree directory. Changes stay isolated until you merge.

Step-by-Step: Running Parallel Claude Sessions

The most common pattern is three terminals, each running Claude on a different task.

claude -w feature-auth "Add OAuth2 login flow"

# Claude creates .claude/worktrees/feature-auth/
# Branch: worktree-feature-auth
# Session scoped to that directory

claude -w bugfix-payment "Fix the race condition in checkout"

# Claude creates .claude/worktrees/bugfix-payment/
# Branch: worktree-bugfix-payment
# Completely isolated from Terminal 1

claude -w test-coverage "Add integration tests for the billing module"

# Claude creates .claude/worktrees/test-coverage/
# Branch: worktree-test-coverage
# Isolated from both Terminal 1 and 2

All three sessions share git history. None can see the others' file changes. When all three finish, you merge the branches in whatever order makes sense.

You can also start a worktree mid-session. Ask Claude to "work in a worktree" or "start a worktree" during an active session and it will create one automatically.

Managing Multiple Worktrees

As you accumulate worktrees, you need to track what exists and what each one is doing.

git worktree list

# Output:
# /Users/you/myproject              abc1234 [main]
# /Users/you/myproject/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
# /Users/you/myproject/.claude/worktrees/bugfix-payment ghi9012 [worktree-bugfix-payment]

# Navigate to the worktree and start Claude
cd .claude/worktrees/feature-auth && claude

# Or use --resume to pick up where you left off
cd .claude/worktrees/feature-auth && claude --continue

Session naming works well with worktrees. Use /rename inside a worktree session to give it a memorable name, then resume it later with claude --resume auth-refactor. The /resume picker shows sessions from all worktrees in the same git repository.

Merging and Cleanup

Automatic Cleanup

When you exit a worktree session, Claude checks for changes:

Merging Worktree Branches

Worktree branches merge like any other branch. From your main working directory:

# From your main working directory
git checkout main

# Merge the feature branch
git merge worktree-feature-auth

# Merge the bugfix
git merge worktree-bugfix-payment

# Push all merged work
git push origin main

If you prefer pull requests, push the worktree branch to the remote and create a PR:

# Inside the worktree session, ask Claude:
> create a PR for my changes

# Or manually:
cd .claude/worktrees/feature-auth
git push origin worktree-feature-auth
gh pr create --title "Add OAuth2 login" --base main

Manual Cleanup

To clean up worktrees outside of a Claude session:

# List worktrees to see what exists
git worktree list

# Remove a specific worktree
git worktree remove .claude/worktrees/feature-auth

# Prune stale worktree references (if directory was deleted manually)
git worktree prune

# Delete the worktree branch if no longer needed
git branch -d worktree-feature-auth

Subagent Worktrees

Subagents can also use worktree isolation. This is useful when you want Claude to delegate subtasks to agents that work in parallel without stepping on each other.

# .claude/agents/researcher.md
---
name: researcher
description: Research codebase patterns before implementation
isolation: worktree
allowed_tools:
  - Read
  - Glob
  - Grep
---

You are a research agent. Explore the codebase to find
relevant patterns and report back to the team lead.

When a subagent has isolation: worktree, it gets its own worktree directory. If the subagent finishes without making changes, the worktree is cleaned up automatically. If it commits changes, those persist in the worktree branch.

You can also ask Claude during a session: "use worktrees for your agents." Claude will configure worktree isolation for any subagents it spawns during that session.

Manual Worktree Management

The --worktree flag handles the common case. For more control, create worktrees with git directly. This is useful when you need a specific existing branch or want the worktree outside the repo directory.

# Worktree outside the repo (e.g. for a long-running task)
git worktree add ~/projects/myapp-feature -b feature-auth

# Worktree from an existing remote branch
git worktree add ../hotfix-dir origin/hotfix-2.1

# Start Claude in the manually created worktree
cd ~/projects/myapp-feature && claude

# When done, remove the worktree
git worktree remove ~/projects/myapp-feature

Worktrees vs Agent Teams

Both enable parallel work. They solve different problems.

The simplest mental model: worktrees are git-level isolation, Agent Teams are AI-level orchestration. You can combine them. Agent Teams use worktrees internally when you configure subagents with isolation: worktree.

Non-Git Version Control

If your team uses Mercurial, Perforce, or SVN, the --worktree flag still works through hooks. Configure WorktreeCreate and WorktreeRemove hooks in your Claude Code settings to replace the default git behavior with your VCS-specific isolation logic.

// .claude/settings.json
{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "p4-create-workspace.sh",
        "description": "Create a Perforce workspace for the worktree"
      }
    ],
    "WorktreeRemove": [
      {
        "command": "p4-delete-workspace.sh",
        "description": "Delete the Perforce workspace"
      }
    ]
  }
}

The hooks receive the worktree name and path as input. Your scripts handle the VCS-specific setup and teardown. When configured, claude --worktree calls your hooks instead of git commands.

FAQ

Do worktrees duplicate my entire repo?

No. Worktrees share the .git directory with the main repo. Only the working files are duplicated. Creating a worktree is milliseconds, not minutes.

Do I need to run npm install in each worktree?

Yes. Worktrees share git objects but not node_modules, Python virtual environments, or other generated directories. Each worktree needs its own dependency installation. Some teams use hooks to automate this.

Can two worktrees check out the same branch?

No. Git enforces that each branch is checked out in at most one worktree. This is a feature, not a limitation. It prevents the exact conflicts worktrees are designed to avoid.

What if I delete a worktree directory manually?

Run git worktree prune to clean up stale references. Git tracks worktrees in .git/worktrees/ and needs to know when a directory no longer exists.

How many worktrees can I run?

There is no git-imposed limit. The practical limit is your machine's disk space and the number of Claude sessions your subscription supports. Three to five parallel worktrees is the common pattern.

Can I use worktrees in the Claude Code Desktop app?

Yes. The Desktop app has had built-in worktree support since before the CLI. Each new session in the Desktop app can optionally get its own worktree.

Where are worktrees stored?

Claude Code creates them at .claude/worktrees/<name>/ inside your repo. For manually created worktrees, you choose the path. Add .claude/worktrees/ to .gitignore to keep them out of your repo status.