Worktrees

Worktrees create isolated working directories for parallel Claude Code sessions. Each worktree has its own branch and files, so you can work on multiple features or bugs simultaneously without changes conflicting.

Official documentation: Run parallel sessions with Git worktrees

Create a Worktree Session

Use the --worktree (or -w) flag to create an isolated session:

# Create named worktree and start Claude
claude --worktree feature-auth

# Auto-generate a random name
claude --worktree

Each worktree:

• Creates a new branch (worktree-<name>) from origin/HEAD
• Branches off the remote's default branch (check with git remote set-head -v)
• Lives in .claude/worktrees/<name>/
• Gets its own git history without affecting the main repo

Multiple Parallel Sessions

Start as many worktrees as you need:

# Terminal 1: Work on auth feature
claude --worktree feature-auth

# Terminal 2: Fix a bug in parallel
claude --worktree bugfix-123

# Terminal 3: Explore a third area
claude --worktree research-perf

Each session is isolated — changes in one worktree don't affect others.

Worktree Cleanup

When exiting a worktree session:

• No changes: Worktree and branch are removed automatically
• With changes: Claude prompts to keep or remove the worktree
  • Keep: Preserves the directory and branch for later resumption
  • Remove: Deletes the worktree and branch, discarding changes

Worktree Setup

Worktrees are fresh git checkouts without untracked files from your main repository. To copy .env, .env.local, or other gitignored files automatically, create a .worktreeinclude file in your project root:

.env
.env.local
config/secrets.json

Only gitignored files matching a pattern are copied. Tracked files are never duplicated.

Subagent Worktrees

Subagents can also use worktrees for parallel isolation. Add to a custom subagent's frontmatter:

isolation: worktree

Subagent worktrees are cleaned up automatically when the subagent finishes.

Related

• Permission Modes - Control what runs without prompting
• Dev Plugin - Team orchestration with /dev:team-feature