Git Worktrees - Claude Code Best Practice

Overview

Git Worktrees allow multiple agents (or developers) to work on different branches simultaneously in separate directories, all from the same repository. This eliminates merge conflicts during active development and enables true parallel work.

Git worktrees are a built-in Git feature that Claude Code can leverage for parallel agent execution with perfect isolation.

The Problem with Shared Branches

When multiple agents work on the same branch:

❌ Traditional Approach

Single Working Directory

Agent A modifies file.ts
Agent B also modifies file.ts
Merge conflict on every commit
Constant pull/push coordination needed
Build breaks if agents aren’t synced

✅ Git Worktrees

Isolated Directories

Agent A: worktree-a/file.ts
Agent B: worktree-b/file.ts
Zero conflicts during development
Each can run tests independently
Merge only when ready

How Git Worktrees Work

Key Concepts

Main Repository

Your original .git directory and working tree. This is the “main” worktree.

/project/
├── .git/
├── src/
└── package.json

Additional Worktrees

Separate directories linked to the same .git, each on a different branch.

/project/
├── .git/
├── src/                    # main worktree (main branch)
├── worktree-frontend/      # feature/ui branch
├── worktree-backend/       # feature/api branch
└── worktree-tests/         # feature/tests branch

Shared Git Database

All worktrees share the same commits, branches, and history. Changes in one worktree don’t affect others until merged.

# In worktree-frontend/
git commit -m "Add UI component"

# In worktree-backend/
# ← Doesn't see the UI commit yet
# ← Can work independently

Basic Usage

Creating Worktrees

# Create worktree for new branch
git worktree add -b feature/ui worktree-frontend

# Result:
# - Creates directory: worktree-frontend/
# - Creates branch: feature/ui
# - Checks out feature/ui in worktree-frontend/

Working in Worktrees

Agent A (Frontend)
Agent B (Backend)
Agent C (Tests)

cd worktree-frontend/

# Work on UI
# Edit src/components/Profile.tsx

git add src/components/Profile.tsx
git commit -m "Add profile component"

# Run tests in isolation
npm test

# Push when ready
git push -u origin feature/ui

cd worktree-backend/

# Work on API
# Edit src/api/profile.ts

git add src/api/profile.ts
git commit -m "Add profile API"

# Run tests in isolation
npm test

# Push when ready
git push -u origin feature/api

cd worktree-tests/

# Work on tests
# Edit tests/profile.test.ts

git add tests/profile.test.ts
git commit -m "Add profile tests"

# Run full test suite
npm test

# Push when ready
git push -u origin feature/tests

Managing Worktrees

git worktree list

# Output:
# /project                     abc1234 [main]
# /project/worktree-frontend   def5678 [feature/ui]
# /project/worktree-backend    ghi9012 [feature/api]

Claude Code Integration

Use worktrees with Claude Code agents for parallel development:

Pattern 1: Agent Isolation Frontmatter

Use the isolation: worktree frontmatter to automatically create worktrees:

.claude/agents/frontend-specialist.md

---
name: frontend-specialist
description: PROACTIVELY handle React and TypeScript work
model: opus
isolation: worktree
color: blue
---

# Frontend Specialist

You work on UI components in complete isolation via git worktree.

## Your Workspace
You're in a dedicated worktree directory. You can:
- Commit without conflicts
- Run tests independently
- Push your branch when ready

## Workflow
1. Make changes to components
2. Commit frequently
3. Run tests: `npm test`
4. Push when phase complete

When you invoke this agent via Task tool, Claude Code automatically creates a worktree on a new branch.

Pattern 2: Manual Worktree Setup

Create worktrees before launching agents:

Create Worktrees

# Set up isolated environments
git worktree add -b feature/profile-ui worktree-ui
git worktree add -b feature/profile-api worktree-api
git worktree add -b feature/profile-tests worktree-tests

Launch Agents in Worktrees

# In main directory, launch agents
# Each agent's workdir points to its worktree

Task(
  subagent_type="frontend-specialist",
  description="Implement UI in worktree-ui",
  prompt="Work in worktree-ui/ directory. Implement profile UI."
)

Task(
  subagent_type="backend-specialist",
  description="Implement API in worktree-api",
  prompt="Work in worktree-api/ directory. Implement profile API."
)

Merge When Ready

# After agents complete and tests pass
git checkout main
git merge feature/profile-api
git merge feature/profile-ui
git merge feature/profile-tests

Real-World Example: E-commerce Feature

Implementing a product review system with 3 parallel agents:

Setup

# Create worktrees for each domain
git worktree add -b reviews/frontend worktree-reviews-ui
git worktree add -b reviews/backend worktree-reviews-api
git worktree add -b reviews/tests worktree-reviews-tests

# Directory structure:
# project/
# ├── .git/
# ├── src/                          # main branch
# ├── worktree-reviews-ui/          # reviews/frontend branch
# ├── worktree-reviews-api/         # reviews/backend branch
# └── worktree-reviews-tests/       # reviews/tests branch

Agent Execution

Frontend Agent
Backend Agent
Testing Agent

Agent Prompt

You are working in worktree-reviews-ui/ directory.

Tasks:
1. Create ReviewList component
2. Create ReviewForm component
3. Add StarRating component
4. Implement review submission

Your workspace:
- Branch: reviews/frontend
- Directory: worktree-reviews-ui/
- Focus: src/components/reviews/

Workflow:
1. Implement each component
2. Commit after each task
3. Run `npm test` to verify
4. Push branch when complete

Agent Prompt

You are working in worktree-reviews-api/ directory.

Tasks:
1. Create Review model
2. Add POST /api/reviews endpoint
3. Add GET /api/reviews/:productId endpoint
4. Implement review validation

Your workspace:
- Branch: reviews/backend
- Directory: worktree-reviews-api/
- Focus: src/api/reviews/

Workflow:
1. Implement each endpoint
2. Commit after each task
3. Run tests: `npm test`
4. Push branch when complete

Agent Prompt

You are working in worktree-reviews-tests/ directory.

Tasks:
1. Unit tests for ReviewList, ReviewForm
2. Unit tests for review API
3. Integration tests for review flow
4. E2E test for submit and display

Your workspace:
- Branch: reviews/tests
- Directory: worktree-reviews-tests/
- Focus: tests/reviews/

Note: You're testing against mocked API contracts.
Actual integration happens after merge.

Merging Strategy

# After all agents complete

# 1. Merge backend first (foundation)
git checkout main
git merge reviews/backend
git push

# 2. Merge frontend (depends on backend types)
git merge reviews/frontend
git push

# 3. Merge tests (validates both)
git merge reviews/tests
git push

# 4. Clean up worktrees
git worktree remove worktree-reviews-ui
git worktree remove worktree-reviews-api
git worktree remove worktree-reviews-tests

# 5. Delete remote branches (optional)
git push origin --delete reviews/frontend
git push origin --delete reviews/backend
git push origin --delete reviews/tests

Advanced Patterns

Shared Dependencies

Problem: node_modules duplicated in each worktree Solution: Symlink shared directories

# After creating worktree
cd worktree-frontend/
rm -rf node_modules
ln -s ../node_modules node_modules

# Or use pnpm (shares node_modules automatically)
pnpm install

Hot Reloading Across Worktrees

Problem: Want to see frontend changes while backend agent runs Solution: Run dev servers from each worktree

# Terminal 1: Frontend dev server
cd worktree-frontend/
npm run dev  # Port 3000

# Terminal 2: Backend dev server
cd worktree-backend/
npm run dev  # Port 4000

# Terminal 3: Run tests
cd worktree-tests/
npm test -- --watch

Integration Testing Across Worktrees

Problem: Need to test frontend + backend together before merging Solution: Temporary integration worktree

# Create integration worktree
git worktree add -b integration/reviews worktree-integration

cd worktree-integration/

# Merge both branches
git merge reviews/frontend
git merge reviews/backend

# Run full integration tests
npm test

# If tests pass, merge both into main
# If tests fail, fix in respective worktrees

Syncing Changes Between Worktrees

Problem: Need to pull latest changes from another branch Solution: Fetch + merge in worktree

# In worktree-frontend/ (on reviews/frontend branch)
cd worktree-frontend/

# Pull latest from backend to sync types
git fetch origin reviews/backend
git merge origin/reviews/backend

# Resolve any conflicts
# Continue frontend work

Best Practices

Do create worktrees for independent workstreams

Do use descriptive worktree directory names

Do clean up worktrees when done

Do commit frequently in each worktree

Do run tests in each worktree before merging

Don’t modify the same file in multiple worktrees simultaneously

Don’t forget to push branches before removing worktrees

Don’t check out the same branch in multiple worktrees (Git prevents this)

Workflows with Worktrees

Boris Cherny’s 5 Patterns

From Boris’s tweet:

1. Parallel Features
2. Hotfix While Developing
3. Review PRs
4. Experiment Safely
5. Agent Teams

# Work on multiple features simultaneously
git worktree add -b feature/auth worktree-auth
git worktree add -b feature/payments worktree-payments
git worktree add -b feature/notifications worktree-notifications

# Each agent/human works independently
# Merge features as they complete

# Main worktree: developing feature
# Urgent bug reported

# Create hotfix worktree from main
git worktree add -b hotfix/critical-bug worktree-hotfix
cd worktree-hotfix/

# Fix bug, test, merge immediately
# Continue feature work in main worktree

# Create worktree to review PR
git worktree add worktree-pr-review pr/123

cd worktree-pr-review/
npm install
npm test

# Review, test, comment
# Remove when done

# Try risky refactoring without affecting main work
git worktree add -b experiment/new-architecture worktree-experiment

# Experiment freely
# If it works: merge
# If it fails: delete worktree, no harm done

# Each agent gets isolated workspace
git worktree add -b agent/frontend worktree-agent-1
git worktree add -b agent/backend worktree-agent-2
git worktree add -b agent/tests worktree-agent-3

# Agents work in parallel
# Zero conflicts during development

Troubleshooting

Error: 'branch is already checked out'

Problem: Trying to check out a branch that’s already active in another worktreeSolution:

# List active worktrees
git worktree list

# Either:
# 1. Use existing worktree for that branch
# 2. Create new branch for new worktree
git worktree add -b feature/ui-v2 worktree-ui

Worktree out of sync

Problem: Worktree shows old commitsSolution:

cd worktree-frontend/

# Pull latest
git pull

# Or fetch + merge specific branch
git fetch origin
git merge origin/feature/ui

Can't remove worktree

Problem: git worktree remove failsSolution:

# Force remove
git worktree remove --force worktree-frontend

# Or manually delete and prune
rm -rf worktree-frontend/
git worktree prune

Lost worktree location

Problem: Forgot where worktrees areSolution:

# List all worktrees with paths
git worktree list

# Output shows full paths:
# /Users/dev/project              abc1234 [main]
# /Users/dev/project/worktree-ui  def5678 [feature/ui]

Comparison with Alternatives

Approach	Conflicts	Isolation	Setup	Best For
Single Branch	High	None	Easy	Solo work, sequential tasks
Feature Branches	Medium	Partial	Easy	Small teams, occasional parallel work
Git Worktrees	None	Complete	Medium	Parallel agents, complex features
Separate Clones	None	Complete	Hard	Complete isolation needed

Agent Teams

Multiple agents working in parallel - perfect with worktrees

RPI Workflow

Phased implementation that can leverage worktrees

Orchestration Workflow

Command → Agent → Skill pattern

Resources

Git Worktree Docs

Official Git documentation

Boris Cherny's Guide

Real-world worktree patterns

Claude Code Isolation

Agent isolation documentation

Best Practices Repo

Community examples and patterns

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

​Overview

​The Problem with Shared Branches

❌ Traditional Approach

✅ Git Worktrees

​How Git Worktrees Work

​Key Concepts

​Basic Usage

​Creating Worktrees

​Working in Worktrees

​Managing Worktrees

​Claude Code Integration

​Pattern 1: Agent Isolation Frontmatter

​Pattern 2: Manual Worktree Setup

​Real-World Example: E-commerce Feature

​Setup

​Agent Execution

​Merging Strategy

​Advanced Patterns

​Shared Dependencies

​Hot Reloading Across Worktrees

​Integration Testing Across Worktrees

​Syncing Changes Between Worktrees

​Best Practices

​Workflows with Worktrees

​Boris Cherny’s 5 Patterns

​Troubleshooting

​Comparison with Alternatives

​Related Patterns

Agent Teams

RPI Workflow

Orchestration Workflow

​Resources

Git Worktree Docs

Boris Cherny's Guide

Claude Code Isolation

Best Practices Repo

Build docs developers (and LLMs) love

Overview

The Problem with Shared Branches

How Git Worktrees Work

Key Concepts

Basic Usage

Creating Worktrees

Working in Worktrees

Managing Worktrees

Claude Code Integration

Pattern 1: Agent Isolation Frontmatter

Pattern 2: Manual Worktree Setup

Real-World Example: E-commerce Feature

Setup

Agent Execution

Merging Strategy

Advanced Patterns

Shared Dependencies

Hot Reloading Across Worktrees

Integration Testing Across Worktrees

Syncing Changes Between Worktrees

Best Practices

Workflows with Worktrees

Boris Cherny’s 5 Patterns

Troubleshooting

Comparison with Alternatives

Related Patterns

Resources