Use git worktrees for parallel Claude Code sessions

Problem

When running multiple AI coding sessions against the same repository, you encounter file write conflicts, uncommitted change collisions, and git index lock errors. Two Claude Code instances editing overlapping files in the same working directory will overwrite each other's changes. Branching alone does not help because git checkout switches the entire working directory.

error: could not lock config file .git/config: File exists
fatal: Unable to create '/project/.git/index.lock': File exists.

Another git process seems to be running in this repo.

Solution

Step 1: Create worktrees for each feature or task

# From your main repo
cd /path/to/my-project

# Create a worktree for feature A on a new branch
git worktree add ../my-project-feature-a -b feature/auth-system

# Create a worktree for feature B on another new branch
git worktree add ../my-project-feature-b -b feature/payment-flow

# List all active worktrees
git worktree list
# /path/to/my-project            abc1234 [main]
# /path/to/my-project-feature-a  def5678 [feature/auth-system]
# /path/to/my-project-feature-b  ghi9012 [feature/payment-flow]

Step 2: Run independent Claude Code sessions in each worktree

# Terminal 1 - working on auth
cd /path/to/my-project-feature-a
claude

# Terminal 2 - working on payments
cd /path/to/my-project-feature-b
claude

Step 3: Merge completed features back

cd /path/to/my-project
git merge feature/auth-system
git merge feature/payment-flow

# Clean up worktrees when done
git worktree remove ../my-project-feature-a
git worktree remove ../my-project-feature-b

Quick helper script for common workflow:

#!/bin/bash
# new-worktree.sh - Create a worktree and open Claude Code in it
BRANCH_NAME="feature/$1"
WORKTREE_PATH="../$(basename $(pwd))-$1"

git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"
echo "Worktree created at $WORKTREE_PATH on branch $BRANCH_NAME"
echo "Run: cd $WORKTREE_PATH && claude"

Why It Works

Git worktrees create separate working directories that share the same .git object store but maintain independent index files, HEAD pointers, and working trees. Each worktree has its own branch checked out, so two Claude Code sessions can read and write files simultaneously without locking conflicts. The shared object store means commits, branches, and history are visible across all worktrees without pushing to a remote.

Context

Anthropic's Claude Code best practices specifically recommend worktrees for parallel AI sessions
Each worktree gets its own CLAUDE.md if needed, allowing different instructions per task
Worktrees are lightweight compared to full clones since they share the git object database
Dev containers combined with worktrees enable fully isolated environments per feature
This pattern works with any AI coding tool (Cursor, Cline, Zed agent), not just Claude Code
Use git worktree prune to clean up stale worktree references after deleting directories