Using Git Worktrees for Parallel Claude Sessions

Overview

Run multiple Claude Code sessions in parallel on the same repository by using Git worktrees. This technique allows you to work on different features or experiments simultaneously without switching branches.

What You'll Learn

How to set up and use Git worktrees to run multiple independent Claude Code sessions on the same codebase.

Prerequisites

• Git 2.5 or newer
• Claude Code CLI installed
• A Git repository

Steps

Step 1: Create a New Worktree

From your main repository, create a new worktree for a specific branch or feature:

git worktree add ../myproject-feature-x feature-x

This creates a new directory ../myproject-feature-x with the feature-x branch checked out.

Step 2: Create Multiple Worktrees

Set up different worktrees for different tasks:

# For a bug fix
git worktree add ../myproject-bugfix bugfix-branch

# For an experiment
git worktree add ../myproject-experiment -b new-experiment

# For reviewing a PR
git worktree add ../myproject-pr-review pr-branch

Step 3: Run Claude Code in Each Worktree

Open separate terminal windows and run Claude Code in each worktree:

# Terminal 1
cd ../myproject-feature-x
claude

# Terminal 2
cd ../myproject-bugfix
claude

# Terminal 3
cd ../myproject-experiment
claude

Step 4: Work in Parallel

Each Claude session operates independently:

• Different branches
• Different file states
• Different contexts
• No interference between sessions

Example Workflow

# Main repository
cd ~/projects/myapp

# Create worktrees for parallel work
git worktree add ../myapp-auth implement-auth
git worktree add ../myapp-ui update-ui
git worktree add ../myapp-tests add-tests

# Run Claude in each
cd ../myapp-auth && claude   # Work on authentication
cd ../myapp-ui && claude      # Work on UI updates
cd ../myapp-tests && claude   # Work on test suite

Managing Worktrees

List All Worktrees

git worktree list

Remove a Worktree

# First, leave the worktree directory
cd ~/projects/myapp
git worktree remove ../myapp-feature-x

Prune Stale Worktrees

git worktree prune

Benefits

• True Parallelism: Run multiple Claude sessions without context switching
• Isolation: Each session has its own working directory
• Speed: No need to stash/switch/pull between tasks
• Comparison: Easy to compare implementations across worktrees

Tips & Best Practices

• Name worktrees descriptively (e.g., myapp-auth, not just auth)
• Keep worktrees in a parallel directory structure
• Clean up worktrees when done to avoid clutter
• Use worktrees for long-running Claude sessions
• Commit changes in each worktree before removing

Common Use Cases

1. Feature Development: Work on multiple features simultaneously
2. Bug Fixes: Fix bugs while continuing feature work
3. Experiments: Try different approaches without affecting main work
4. Code Reviews: Review PRs while working on other tasks
5. A/B Testing: Compare different implementations side-by-side

Troubleshooting

Issue: "fatal: 'feature-x' is already checked out" Solution: You can't have the same branch in multiple worktrees. Create a new branch or use a different existing branch.

Issue: Worktree directory already exists Solution: Choose a different directory name or remove the existing directory first.

References

• Git Worktree Documentation