Claude Code Git Worktrees

How to use git worktrees with Claude Code to run multiple parallel, isolated coding sessions on different branches simultaneously. Setup, patterns, and best practices for parallel AI-assisted development.

Git worktrees let you check out multiple branches simultaneously in separate directories. Combined with Claude Code, they enable parallel AI-assisted development — one session fixing a bug on main while another builds a feature on a separate branch, with zero interference.

Setup: create a worktree

# Create a worktree for a new feature branch
git worktree add ../my-project-feature feature/payment-v2

# Or create the branch and worktree together
git worktree add -b feature/payment-v2 ../my-project-feature

# List all worktrees
git worktree list

You now have two directories:

• ~/my-project/ — original, on main
• ~/my-project-feature/ — worktree, on feature/payment-v2

Run Claude Code in each worktree

# Terminal 1 — main branch
cd ~/my-project
claude "Fix the null pointer in OrderProcessor.process()"

# Terminal 2 — feature branch (simultaneously)
cd ~/my-project-feature
claude "Build the PaymentGateway interface and Stripe implementation"

Both sessions run concurrently. Changes in one directory have no effect on the other.

Typical parallel development patterns

Sharing CLAUDE.md across worktrees

Create CLAUDE.md in the repo root once. Each worktree inherits it automatically (it's part of the git history). No symlinks needed — git tracks it like any other file.

# CLAUDE.md lives in the repo root
ls ~/my-project/CLAUDE.md        # exists
ls ~/my-project-feature/CLAUDE.md  # also exists (same file, different worktree)

Worktrees in Claude Code's own subagent system

Claude Code uses the worktree pattern internally when spawning subagents with the isolation: "worktree" option. Each subagent gets an isolated copy of the repo on a temporary branch, does its work, and the results are merged back. You can replicate this pattern in your own orchestration:

import subprocess, os

def claude_in_worktree(branch: str, prompt: str, base_dir: str) -> str:
    worktree_path = f"/tmp/wt-{branch}"
    subprocess.run(["git", "worktree", "add", "-b", branch, worktree_path], cwd=base_dir)
    try:
        result = subprocess.run(
            ["claude", "--print", prompt],
            cwd=worktree_path,
            capture_output=True, text=True
        )
        return result.stdout
    finally:
        subprocess.run(["git", "worktree", "remove", "--force", worktree_path], cwd=base_dir)
        subprocess.run(["git", "branch", "-D", branch], cwd=base_dir)

Cleanup

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

# Force remove (if Claude Code left uncommitted files)
git worktree remove --force ../my-project-feature

# Prune stale worktree references
git worktree prune

Worktrees vs. Docker containers for isolation

For running Claude Code without any interactive session (batch pipelines, CI), see Claude Code headless mode. For coordinating multiple Claude Code agents programmatically, see Claude Code multi-agent patterns.

Frequently asked questions

Free tools

More examples