Claude Code Worktree Guide — Safe Parallel Development Techniques

What is a Worktree?

Git's worktree feature lets you check out multiple branches simultaneously in separate directories from a single repository. Claude Code natively supports this, allowing you to work on separate tasks without interrupting your main workflow.

Basic Usage

Starting a Worktree in Claude Code

Simply ask Claude Code to "work in a worktree" and it automatically creates one.

# In Claude Code's prompt:
> Fix this bug in a worktree
 
# What Claude Code does automatically:
# 1. Creates a new worktree under .claude/worktrees/
# 2. Creates a new branch from HEAD
# 3. Starts working in that directory

Manual Worktree Creation

You can also create worktrees using Git commands directly.

# Create a new worktree with a new branch
git worktree add ../my-feature -b feature/new-login
 
# Check out an existing branch as a worktree
git worktree add ../hotfix-dir hotfix/critical-bug
 
# List all worktrees
git worktree list

Practical Scenarios

Scenario 1: Emergency Hotfix During Feature Work

When a production bug needs fixing while you're developing a new feature, worktrees let you respond without interrupting your current work.

Current state:
  main branch → main worktree (feature development in progress)

Emergency fix:
  hotfix branch → separate worktree for the fix

Example in Claude Code:

# Your main working directory stays untouched
> Fix the production login error in a worktree.
> Create a hotfix/login-error branch from main.

Claude Code fixes the bug in a separate directory and creates a PR. Your main working directory is completely unaffected.

Scenario 2: Working on Multiple PRs Simultaneously

Worktrees are ideal for parallel development of different features.

# Worktree 1: Auth improvements
git worktree add ../auth-improvement -b feature/auth-v2
 
# Worktree 2: Dashboard feature
git worktree add ../dashboard-feature -b feature/dashboard
 
# Worktree 3: Performance tuning
git worktree add ../perf-tuning -b perf/optimize-queries

Each worktree is independent, so builds and tests don't interfere with each other.

Scenario 3: Parallel Work with Scheduled Tasks

When Cowork scheduled tasks auto-commit to a repository, manual work might conflict. Worktrees provide safe isolation.

# Main worktree: scheduled tasks auto-commit to main
# Manual worktree: UI improvements on a separate branch
git worktree add ../ui-redesign -b feature/ui-redesign
 
# After completion, merge into main
git checkout main
git merge feature/ui-redesign

Managing Worktrees

Listing Worktrees

git worktree list
# /home/user/myproject         abc1234 [main]
# /home/user/myproject-hotfix  def5678 [hotfix/login-error]
# /home/user/myproject-feature ghi9012 [feature/dashboard]

Removing Worktrees

Delete completed worktrees to save disk space.

# Remove a worktree
git worktree remove ../myproject-hotfix
 
# Force remove (with uncommitted changes)
git worktree remove --force ../myproject-hotfix
 
# Clean up stale references
git worktree prune

Auto-Cleanup in Claude Code

When using worktrees in Claude Code, you'll be prompted to keep or remove them when the session ends. Worktrees with no changes are automatically cleaned up.

Tips and Best Practices

Same Branch Cannot Be Used Twice

A branch can only be checked out in one worktree at a time.

# This will fail
git worktree add ../second-main main
# fatal: 'main' is already checked out at '/home/user/myproject'

Handling node_modules

Each worktree is a separate directory, so dependencies need individual installation.

cd ../my-feature
npm install  # Required for each worktree

What's Shared Between Worktrees

The .git directory is shared with the original repository, so these are common across all worktrees: Git configuration, remote settings, reflog, and Git hooks.

These are independent per worktree: working files (source code), staging area (index), and HEAD reference (checked-out branch).

Advanced Claude Code Integration

Task Tool with Worktree Isolation

Claude Code's Task tool supports isolation: "worktree", which runs sub-agents in their own worktree automatically.

Specify isolation: "worktree" in the Task tool
→ Sub-agent works in an isolated worktree
→ Returns branch and path if changes were made
→ No impact on main work

The /worktree Slash Command

Claude Code provides the /worktree command for interactive worktree management.

> /worktree       # Opens worktree management menu

Looking back

Worktrees are a powerful feature that makes parallel development in Claude Code safe and efficient. They let you handle emergencies without interrupting your main work, develop multiple PRs simultaneously, and avoid conflicts with scheduled tasks. Free yourself from the friction of branch switching and build a smoother development workflow.