Worktrees — Parallel Isolated Sessions

A git worktree is a separate working directory on a new branch, sharing the same repository history as your main checkout. Each Claude session in its own worktree means edits in one session never touch files in another.

Use case: Have Claude building a feature in one terminal while fixing a bug in a second — zero file conflicts.

Start a Worktree Session

# Named worktree → creates .claude/worktrees/feature-auth/ on branch worktree-feature-auth
claude --worktree feature-auth

# Auto-named → creates something like .claude/worktrees/bright-running-fox/
claude --worktree

# Shorthand
claude -w bugfix-123

Add .claude/worktrees/ to your .gitignore so worktree contents don’t appear as untracked files.

From a Specific PR

# Check out PR #1234 as a worktree
claude --worktree "#1234"

Claude fetches pull/1234/head from origin and creates the worktree at .claude/worktrees/pr-1234.

Choosing the Base Branch

By default, worktrees branch from origin/HEAD (your repo’s default branch).

To always branch from your current local HEAD instead:

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

Options: "fresh" (default, from origin) or "head" (from local HEAD).

"head" is useful when subagents need to operate on in-progress (unpushed) work.

Copy Gitignored Files into Worktrees

A worktree is a fresh checkout — .env, .env.local, etc. are not copied automatically.

Create a .worktreeinclude file at the project root to copy specific gitignored files:

.env
.env.local
config/secrets.json

Only files matching these patterns AND that are gitignored get copied. Tracked files are never duplicated.

This applies to all worktrees: --worktree, subagent worktrees, and Desktop parallel sessions.

Subagents with Worktrees

Give each parallel subagent its own isolated worktree so edits don’t conflict:

---
name: feature-builder
isolation: worktree
---

Or ask at runtime:

Use worktrees for your agents when working in parallel

Subagent worktrees are automatically cleaned up when the subagent finishes with no changes.

Desktop App

The Desktop app creates a worktree for every new session automatically — no manual setup needed.

Cleanup Behavior

Situation	What happens
No uncommitted changes, no new commits	Worktree + branch removed automatically
Uncommitted changes or new commits exist	Claude prompts: keep or remove?
Non-interactive (`-p` flag)	NOT auto-cleaned. Run `git worktree remove` manually
Subagent/background worktrees older than `cleanupPeriodDays`	Swept automatically (if no uncommitted changes)

Manual Worktree Management with Git

For full control:

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

# Create from an existing branch
git worktree add ../project-bugfix bugfix-123

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

# List all worktrees
git worktree list

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

Non-Git Version Control (SVN, Perforce, Mercurial)

Configure WorktreeCreate and WorktreeRemove hooks in settings.json:

{
  "hooks": {
    "WorktreeCreate": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
      }]
    }]
  }
}

When using WorktreeCreate, .worktreeinclude is not processed — copy config files inside your hook script.

Typical Parallel Workflow

# Terminal 1: work on auth feature
claude --worktree auth-feature
# Claude edits .claude/worktrees/auth-feature/...

# Terminal 2: fix a bug simultaneously
claude --worktree bugfix-payment
# Claude edits .claude/worktrees/bugfix-payment/...

# No conflicts — completely separate directories and branches

Subagents — delegate work to isolated agents within a session
Agent Teams — multiple Claude sessions that coordinate
Desktop App — auto-worktree for every session

🧠 Quick Recall

Trick: “One branch, one folder, one Claude.”

👨‍🏫 Teach It

Show: two worktrees, two terminals, two features advancing at once.
They’ll trip on: cleanup — git worktree prune after merging.

Learning path: ⬅ 30-agent-project-structure.md · Index · ➡ 32-agent-teams.md

Written by Fenil Patel