Worktree Parallel Development

Running Claude Code in several terminals at once causes conflicts when they modify the same file simultaneously. With the --worktree flag, each session works in an isolated copy of the code, so you can develop in parallel without conflicts.

Core concepts

Project root (main branch)
├── src/
├── .claude/
│   └── worktrees/
│       ├── feature-auth/      ← Session A (worktree-feature-auth branch)
│       │   └── src/
│       └── bugfix-123/        ← Session B (worktree-bugfix-123 branch)
│           └── src/

Each worktree has:

• An independent Git branch (worktree-<name>)
• An independent copy of the file system
• An independent Claude Code session

How to use it

Basic usage

# Start a worktree with a specified name
claude --worktree feature-auth

# A separate worktree in another terminal
claude --worktree bugfix-123

# Short flag
claude -w feature-auth

# Auto-generate a name (e.g., bright-running-fox)
claude --worktree

Switching worktrees mid-session

You can request it in natural language during a conversation:

> Work in a worktree
> Start a new worktree

Claude automatically creates and switches to a worktree.

Directory structure

Item	Path
Worktree directory	<project>/.claude/worktrees/<name>/
Branch name	worktree-<name>
Base branch	Default remote branch (usually main)

Add to .gitignore

Add .claude/worktrees/ to your .gitignore. This prevents worktree directories from being committed by accident.

Subagent isolation

Custom subagents can use worktree isolation too:

---
name: refactor-agent
isolation: worktree
---

This agent performs code refactoring.
If there are no changes, the worktree is cleaned up automatically.

A subagent's worktree:

• Exits with no changes → auto-deleted
• Has changes/commits → returns the worktree path and branch

Cleaning up worktrees

When you end a session, Claude checks:

• No changes: the worktree and branch are auto-deleted
• Has changes: a keep/delete prompt
  • Keep: preserve the directory and branch (delete later manually with git worktree remove)
  • Delete: delete everything, including uncommitted changes

# Manual cleanup
git worktree list                          # List all worktrees
git worktree remove .claude/worktrees/feature-auth  # Remove a specific worktree
git branch -d worktree-feature-auth        # Delete the branch

Practical usage patterns

Pattern 1: A feature and a bug fix in parallel

# Terminal 1: new feature development
claude -w feature-payment
> Implement the payment module

# Terminal 2: urgent bug fix
claude -w hotfix-login
> Fix the login session expiration bug

Since each works on an independent branch, you create separate PRs to main when done.

Pattern 2: Comparing experimental approaches

# Approach A: REST API
claude -w approach-rest
> Implement the notification system with a REST API

# Approach B: WebSocket
claude -w approach-websocket
> Implement the notification system with WebSocket

Compare the two results and pick the better approach.

Pattern 3: Combining with Agent Teams

In Agent Teams (Level 5), having each team member work in a separate worktree lets you develop in parallel without file conflicts:

Team leader (main)
├── Member A → worktree-frontend (UI development)
├── Member B → worktree-backend  (API development)
└── Member C → worktree-tests    (writing tests)

Background agents and persistent approvals

The worktree workflow has become smoother in recent versions in two ways.

Automatic commit, push, and draft PR (v2.1.198+) — when a background agent launched with claude agents finishes its code work in a worktree, instead of stopping to ask, it automatically commits, pushes, and even creates a draft PR. As in Pattern 1, you no longer have to handle the "create a separate PR when done" step yourself — the finished work arrives as a draft PR, so you just review and merge.

Persisting 'always allow' rules across worktrees (v2.1.211+) — 'always allow' permission rules are now stored at the repository root. An approval granted inside a worktree persists across sessions and worktrees, so you no longer have to repeat the same tool approvals every time you create a new worktree.

Support for VCS other than Git

If you use Mercurial, Perforce, SVN, or the like, you can implement custom worktree logic with hooks:

// .claude/settings.json
{
  "hooks": {
    "WorktreeCreate": [{
      "command": "./scripts/create-worktree.sh $WORKTREE_NAME"
    }],
    "WorktreeRemove": [{
      "command": "./scripts/remove-worktree.sh $WORKTREE_PATH"
    }]
  }
}

Once these hooks are set, the --worktree flag runs your custom scripts instead of Git.

Caveats

Dependencies across worktrees

Each worktree is an independent file system, so dependencies installed with npm install are not shared. You must install dependencies separately in each worktree.

• Worktrees use additional disk space (project size × number of worktrees)
• If you have heavy directories like node_modules, creation can take a while
• Memory (Auto Memory) in a worktree is managed separately from the main project