to Parallel Development with Claude Code Worktrees

Claude Code Worktree Integration

Worktree-Aware Operations

Claude Code supports explicit worktree targeting:

# Basic syntax
claude --worktree=<path> --context="<task description>"
 
# Example
claude --worktree=../feature-auth-work \
       --context="Implement OAuth 2.0 authentication system"

Isolation and Safety Features

The --isolated flag provides strict separation:

• Filesystem constraints - Only worktree-local files accessible
• Git operation boundaries - Commits stay within worktree scope
• Cross-worktree isolation - No interference between parallel sessions

# Strict isolation mode
claude --worktree=../feature-payment-work \
       --isolated \
       --context="Implement Stripe payment integration"

Setting Up Parallel Development

Phase 1: Repository Assessment

Begin by understanding your current setup:

cd ~/my-project
 
# Current repository status
git status
git branch -a
 
# Existing worktrees (if any)
git worktree list

Phase 2: Directory Structure Design

Establish a clear naming convention for worktree organization:

~/projects/
└── my-project/
    ├── .git/                           # Shared Git metadata
    ├── main-work/                      # Main branch worktree
    ├── feature-authentication-work/    # Feature development
    ├── feature-payments-work/          # Concurrent feature
    ├── hotfix-critical-issue-work/     # Emergency fixes
    └── release-v2-0-work/              # Release preparation

This structure maintains one .git directory while supporting multiple independent worktrees.

Phase 3: Worktree Creation and Initialization

Create worktrees for your planned parallel tasks:

# Main branch worktree
git worktree add main-work main
 
# Feature development (new branch)
git worktree add feature-auth-work -b feature/authentication
 
# Bug fix (existing branch)
git checkout -b bugfix/critical-issue
git worktree add bugfix-work bugfix/critical-issue
 
# Verify setup
git worktree list

Expected output:

/home/user/my-project/main-work              main
/home/user/my-project/feature-auth-work      feature/authentication
/home/user/my-project/bugfix-work            bugfix/critical-issue

Phase 4: Managing Multiple Claude Code Sessions

Launch independent Claude Code sessions for each worktree:

# Terminal 1: Primary feature development
cd feature-auth-work
claude --context="OAuth 2.0 implementation with session management"
 
# Terminal 2: Parallel bug investigation
cd bugfix-work
claude --context="Debug production authentication timeout issue"
 
# Terminal 3: Documentation update
cd main-work
claude --context="Update API documentation"

Each session operates with independent context, eliminating cross-session interference.

Feature Development Workflow in Depth

Initialization Phase

# Start from repository root
cd ~/my-project
 
# Ensure main is current
git fetch origin main
git checkout main
git pull origin main
 
# Create and checkout feature branch
git checkout -b feature/user-dashboard
 
# Create dedicated worktree
git worktree add feature-dashboard-work feature/user-dashboard
cd feature-dashboard-work

Implementation Phase

Initiate Claude Code with detailed context:

claude --worktree=. \
       --context="Implement user dashboard with:
       - Activity timeline for past 7 days
       - Tech stack: TypeScript + React
       - Styling: Tailwind CSS
       - Authentication: Existing useAuth hook"

Claude Code automatically:

1. Creates component structure (src/components/Dashboard.tsx)
2. Generates TypeScript interfaces
3. Writes Storybook stories
4. Creates unit tests
5. Stages changes (git add src/)

Pre-PR Verification

# Run test suite
npm test
 
# Build verification
npm run build
 
# Type checking
npx tsc --noEmit
 
# Linting
npm run lint
 
# Review commits
git log --oneline main..feature/user-dashboard

PR Preparation

# Optionally clean up commits
git rebase -i main
 
# Final status check
git status
 
# Push to remote
git push origin feature/user-dashboard

Create PR via GitHub UI while other worktrees continue work.

Concurrent Bug Fixes and Feature Development

Multiple worktrees shine when production incidents occur mid-feature-development.

Scenario Management

• In progress - Feature development in feature-dashboard-work
• Incident - Production login timeout error reported
• Response - Parallel bug investigation and fix

Creating Emergency Fix Worktree

From a new terminal, without interrupting feature development:

cd ~/my-project
 
# Create hotfix branch from current main
git fetch origin main
git checkout main
git pull origin main
git checkout -b hotfix/login-timeout
 
# Create isolated worktree
git worktree add hotfix-work hotfix/login-timeout
cd hotfix-work
 
# Initiate investigation
claude --worktree=. \
       --context="Fix production authentication timeout
       - Error: 'Request timeout after 30s'
       - Frequency: Multiple regions simultaneously
       - Hypothesis: Auth API rate limiting exceeded
       - Solution approach: Timeout value tuning and connection pool optimization"

Parallel Execution State

# Window 1: Feature development continues
cd feature-dashboard-work
# ... ongoing work
 
# Window 2: Bug fix investigation
cd hotfix-work
# ... debugging and solution implementation
 
# Window 3: Monitoring/management
cd main-work
git log --oneline -10

Git maintains complete separation across all three worktrees.

Merge and Cleanup

Once hotfix is complete and merged to main:

# Test hotfix thoroughly
cd hotfix-work
npm test
npm run build
 
# Push for PR review
git push origin hotfix/login-timeout
 
# After merge on GitHub...
 
# Remove worktree
cd ~/my-project
git worktree remove hotfix-work
 
# Clean up local branch reference
git branch -d hotfix/login-timeout

Advanced: Agent Mode with Worktrees

Claude Code's agent mode combines with worktrees for powerful autonomous development:

Agent Mode Activation

cd feature-auth-work
 
# Agent-mode auto-execution
claude --worktree=. \
       --agent \
       --context="Complete authentication feature:
 
       Requirements:
       - JWT token management
       - Refresh token support
       - CSRF protection
       - Audit logging
 
       Implementation steps:
       1. Create utility functions (src/utils/auth.ts)
       2. Build server endpoints (src/api/auth/)
       3. Implement client components (src/components/Auth/)
       4. Write E2E tests
       5. Generate documentation"

Agent mode autonomously:

• Evaluates implementation requirements
• Checks for conflicts with existing code
• Creates tests and validates
• Stages commits automatically

Orchestrating Multiple Agents

#!/bin/bash
 
# Agent 1: Authentication feature
(cd feature-auth-work && \
 claude --worktree=. --agent --context="OAuth implementation") &
 
# Agent 2: UI components
(cd feature-ui-work && \
 claude --worktree=. --agent --context="Form component suite") &
 
# Agent 3: Documentation
(cd docs-work && \
 claude --worktree=. --agent --context="API docs generation") &
 
# Wait for all background processes
wait
 
echo "All parallel tasks completed"

Troubleshooting Common Issues

Issue 1: Branch Already Checked Out

$ git worktree add work2 main
fatal: 'main' is already checked out at '/path/to/work1'

Solution:

# Create new branch for second worktree
git worktree add work2 -b main-secondary main
# Or use alternative existing branch
git worktree add work2 develop

Issue 2: Worktree Removal Failures

$ git worktree remove feature-work
fatal: '/path/to/feature-work' is not a working tree root

Solution:

# Verify registered worktrees
git worktree list
 
# Remove with full path
git worktree remove /full/path/to/feature-work
 
# Force removal if necessary
git worktree remove --force feature-work

Issue 3: Merge Conflicts Between Worktrees

$ git merge main
CONFLICT (content): Merge conflict in src/utils/api.ts

Resolution:

# Review conflict details
git diff src/utils/api.ts
 
# Manually resolve in editor, then
git add src/utils/api.ts
git commit -m "Merge main: resolve api.ts conflicts"

Issue 4: Disk Space Management

Multiple worktrees in large repositories consume significant space:

# Check worktree disk usage
du -sh ~/projects/my-project/*/
 
# Clean dangling references
git worktree prune

CI/CD Integration with Worktrees

CI/CD pipelines benefit significantly from worktree parallelization:

GitHub Actions Example

name: Parallel Testing with Worktrees
 
on: [push, pull_request]
 
jobs:
  test-matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        suite: [unit, integration, e2e]
    steps:
      - uses: actions/checkout@v3
 
      - name: Create worktree for ${{ matrix.suite }}
        run: |
          git worktree add test-${{ matrix.suite }} ${{ github.ref }}
          cd test-${{ matrix.suite }}
 
      - name: Install dependencies
        run: |
          cd test-${{ matrix.suite }}
          npm ci
 
      - name: Run ${{ matrix.suite }} tests
        run: |
          cd test-${{ matrix.suite }}
          npm run test:${{ matrix.suite }}

This configuration executes unit, integration, and E2E tests in parallel, significantly reducing total CI time.

A Note from an Indie Developer

Key Takeaways

Git worktrees combined with Claude Code represent a paradigm shift in development efficiency. The ability to maintain multiple independent task contexts without context-switching overhead fundamentally changes how teams approach parallel development.

While the learning curve exists, the productivity gains—especially for teams managing concurrent features, bug fixes, and releases—justify the investment immediately. Teams embracing this workflow typically report 30-40% reductions in development cycle time and significantly improved code quality due to fewer interrupted contexts.

Start with your most time-critical parallel scenario and expand from there. The patterns and commands provided in this guide form a complete reference for implementing worktree-based workflows in any project.

Part 1: Worktrees from Basics to Advanced Patterns

1.1 Understanding Worktrees

Git worktrees let you maintain multiple working directories for a single repository simultaneously. Traditional branch switching (git checkout) swaps context in the same directory. Worktrees, by contrast, create physically separate directories, each with its own independent workspace.

# Parent worktree (main checkout)
/project/
├── .git/
├── src/
└── ...
 
# Child worktree 1
/project/wt-feature-auth/
├── src/
└── ...
 
# Child worktree 2
/project/wt-feature-payments/
├── src/
└── ...

Each worktree can check out a different branch, enabling simultaneous editing of different code. This is the foundation of parallel development.

1.2 Worktree Operations in Claude Code

Create a new worktree in Claude Code using the --worktree flag:

claude-code create --project /path/to/repo --worktree feature/auth

This command performs:

1. Creates /path/to/repo/wt-feature-auth directory
2. Creates and checks out the feature/auth branch
3. Generates .claude-code-context.md in the new worktree
4. Initializes independent environment configuration

Critical Configuration: Each worktree has an independent CLAUDE.md scope. Development guidelines defined in the parent worktree don't automatically apply to children. In large projects, careful management of worktree-specific scope files is key to maintaining quality consistency.

1.3 Worktree Lifecycle Management

Worktrees follow a clear lifecycle from creation to destruction:

Phase 1: Initialization (0–5 minutes)

• Worktree creation
• Dependency installation (npm install, etc.)
• Local test environment setup

Phase 2: Implementation (5 minutes–several hours)

• Feature code authoring
• Unit test implementation
• Local test execution

Phase 3: Integration Testing (post-implementation)

• Merge conflict detection with parent branch
• End-to-end test execution
• Code quality scanning

Phase 4: Closure (post-integration)

• Pull request merge
• Worktree deletion
• Remote branch cleanup

Delete a worktree with:

# Remove worktree
git worktree remove wt-feature-auth
 
# Delete branch
git branch -d feature/auth
 
# Delete remote branch
git push origin --delete feature/auth

Important: The --force flag during deletion can lose unsaved changes. Always verify with git worktree list before removing.

Part 2: Sub-Agent Architecture

2.1 Claude Code's Multi-Agent Design

Claude Code can spin up a maximum of 7 parallel agents. Each agent runs on its own execution thread, sharing CPU/memory resources while working on different worktrees independently.

Basic multi-agent configuration:

Parent Agent (coordinator)
├─ Sub-Agent 1 → Worktree 1 → Feature A (auth)
├─ Sub-Agent 2 → Worktree 2 → Feature B (payments)
├─ Sub-Agent 3 → Worktree 3 → Feature C (notifications)
├─ Sub-Agent 4 → Worktree 4 → Testing & CI
├─ Sub-Agent 5 → Worktree 5 → Documentation
├─ Sub-Agent 6 → Worktree 6 → Quality assurance
└─ Sub-Agent 7 → Worktree 7 → Deployment

2.2 Spawning and Managing Sub-Agents

Spawn a child agent from the parent using Claude Code's API:

// Code in parent agent
const subAgent = await spawnAgent({
  projectPath: "/path/to/repo/wt-feature-auth",
  instructions: "Complete the TypeScript implementation of the auth module...",
  maxIterations: 20,
  timeout: 3600, // 1 hour
});
 
// Monitor child agent progress
const result = await subAgent.waitForCompletion();
if (result.success) {
  console.log("Auth feature implementation complete");
} else {
  console.log(`Error: ${result.error}`);
}

Core Design Principles:

• Assign each sub-agent a single responsibility (Single Responsibility Principle)
• Always declare dependencies between sub-agents upfront
• Set timeout values based on project complexity (typically 300–3600 seconds)

2.3 Inter-Agent Communication Patterns

For multiple agents to coordinate efficiently, clear communication interfaces are essential.

Pattern 1: Task Wait Model (most common) The parent agent waits for child agents to complete, then aggregates results. Best for strong dependencies.

const auth = await spawnAgent({ ... }).waitForCompletion();
const payment = await spawnAgent({ ... }).waitForCompletion();
const notification = await spawnAgent({ ... }).waitForCompletion();
// Run integration tests after all complete

Pattern 2: Fire-and-Forget (non-blocking) The parent spawns child agents but continues without waiting for completion. Best for weak dependencies.

const agents = [
  spawnAgent({ ... }), // non-blocking
  spawnAgent({ ... }),
  spawnAgent({ ... }),
];
// Parallel wait for all agents
await Promise.all(agents.map(a => a.waitForCompletion()));

2.4 Resource Limits and Load Balancing

Running 7 agents simultaneously creates pressure on system resources (CPU/memory). Claude Code has built-in load balancing:

• CPU Throttling: Each agent allocated max 25% CPU
• Memory Pool: 75% of total memory shared across agents
• I/O Scheduling: Disk read/write operations queued

In practice, limit concurrent agents based on system specs:

• 4-core PC: Max 3–4 agents
• 8-core PC: Max 5–6 agents
• 16+ cores: Max 7 agents

Part 3: Task Management System

3.1 How CLAUDE_CODE_TASK_LIST_ID Works

All Claude Code agents share a single unified task list. This list's ID is defined via the CLAUDE_CODE_TASK_LIST_ID environment variable.

Task list structure:

{
  "id": "task-abc123xyz",
  "project_path": "/path/to/repo",
  "tasks": [
    {
      "id": "t-auth-001",
      "title": "Create auth module type definitions",
      "status": "in_progress",
      "assignee": "agent-1",
      "priority": 1,
      "due_date": "2026-03-30T20:00Z",
      "dependencies": []
    },
    {
      "id": "t-payment-001",
      "title": "Implement payment flow tests",
      "status": "pending",
      "assignee": null,
      "priority": 2,
      "due_date": "2026-03-30T21:00Z",
      "dependencies": ["t-auth-001"]
    }
  ],
  "last_updated": "2026-03-30T19:45Z"
}

Each agent updates this list in real-time. The parent agent periodically polls it to track overall progress.

3.2 Progress Synchronization Implementation Patterns

Efficient parallel development requires real-time progress synchronization. Here's the standard implementation pattern:

// Parent agent: initialize task list
const taskList = {
  id: process.env.CLAUDE_CODE_TASK_LIST_ID,
  tasks: [
    { id: "t1", title: "Auth", status: "pending", dependencies: [] },
    { id: "t2", title: "Payment", status: "pending", dependencies: ["t1"] },
    { id: "t3", title: "Notification", status: "pending", dependencies: ["t1", "t2"] },
  ]
};
 
// Sub-agent 1: execute task
async function executeTask(taskId) {
  await updateTaskStatus(taskId, "in_progress");
  try {
    // implementation...
    await updateTaskStatus(taskId, "completed");
  } catch (error) {
    await updateTaskStatus(taskId, "failed", error.message);
    // retry logic...
  }
}
 
// Parent agent: monitor progress
async function monitorProgress() {
  const interval = setInterval(() => {
    const completed = taskList.tasks.filter(t => t.status === "completed").length;
    const total = taskList.tasks.length;
    console.log(`Progress: ${completed}/${total}`);
  }, 5000);
}

3.3 Dependency Control and Ordering

Task execution order is controlled by a dependency graph. If Task B depends on Task A, B only starts after A completes.

Example dependency graph:

Auth Module (t-auth)
├─ Payment Module (t-payment)
│  └─ Notification Module (t-notification)
└─ User Profile (t-profile)
   └─ Notification Module (t-notification)

→ Execution order: t-auth → [t-payment, t-profile] → t-notification

Explicitly declaring dependencies allows Claude Code to automatically compute the optimal execution sequence. This maximizes parallelism even in projects with limited agent count.

Part 4: Implementation Patterns and Operations

4.1 Fan-Out/Aggregation Pattern

The most effective parallel pattern for large projects is fan-out/aggregation.

Flow:

1. Parent agent distributes multiple independent tasks to child agents (fan-out)
2. Each child agent processes independently
3. Parent agent collects and integrates all results (aggregation)

// Example: simultaneous module development
async function fanOutAggregation() {
  const features = [
    { name: "auth", branch: "feature/auth" },
    { name: "payment", branch: "feature/payment" },
    { name: "notification", branch: "feature/notification" },
  ];
 
  // Fan-out: launch all modules concurrently
  const agents = features.map(f =>
    spawnAgent({
      worktree: f.branch,
      task: `Complete implementation of ${f.name} module`,
    })
  );
 
  // Aggregation: wait for all results
  const results = await Promise.all(
    agents.map(a => a.waitForCompletion())
  );
 
  // Integration processing
  for (const result of results) {
    if (!result.success) {
      console.error(`${result.feature} failed`);
      // recovery logic...
    }
  }
 
  return results;
}

4.2 Pipeline Pattern

When dependencies are strong, the pipeline pattern is effective. Output from one stage becomes input to the next.

Stage 1: Code Generation
  ↓
Stage 2: Unit Testing
  ↓
Stage 3: Integration Testing
  ↓
Stage 4: Deployment

Stage implementation:

async function pipelineExecution() {
  // Stage 1
  const codeGenResult = await spawnAgent({
    task: "Generate API endpoint skeleton code"
  }).waitForCompletion();
 
  // Stage 2
  const unitTestResult = await spawnAgent({
    task: "Create unit tests for generated code",
    context: codeGenResult,
  }).waitForCompletion();
 
  // Stage 3
  const integrationResult = await spawnAgent({
    task: "Run integration tests with existing modules",
    context: unitTestResult,
  }).waitForCompletion();
 
  // Stage 4
  const deployResult = await spawnAgent({
    task: "Deploy to staging environment",
    context: integrationResult,
  }).waitForCompletion();
 
  return deployResult;
}

4.3 Hierarchical Delegation Pattern

For massive projects, the parent doesn't manage all tasks directly. Instead, it delegates hierarchically.

Level 1: Project parent agent
├─ Level 2: Backend parent agent
│  ├─ Level 3: Auth team sub-agent
│  ├─ Level 3: Payment team sub-agent
│  └─ Level 3: Notification team sub-agent
└─ Level 2: Frontend parent agent
   ├─ Level 3: UI components sub-agent
   └─ Level 3: Page integration sub-agent

This structure ensures each layer maintains appropriate scope and responsibility.

4.4 Production Workflow in Practice

A real project example (e.g., e-commerce platform refactoring):

Day 1 Morning: Planning Phase

• Parent agent analyzes and segments the project
• Measures code complexity, maps dependencies
• Divides into 7 sub-tasks

Day 1 Mid-Morning: Implementation Phase

Sub-Agent 1 → Worktree 1 → Database schema update
Sub-Agent 2 → Worktree 2 → API layer refactoring
Sub-Agent 3 → Worktree 3 → Auth logic optimization
Sub-Agent 4 → Worktree 4 → Unit test expansion
Sub-Agent 5 → Worktree 5 → Type definition strictness
Sub-Agent 6 → Worktree 6 → Documentation updates
Sub-Agent 7 → Worktree 7 → CI/CD pipeline adjustment

Each agent progresses independently. Task management system auto-handles dependencies.

Day 1 Afternoon: Integration Testing Phase

• After all sub-tasks complete, parent runs integration tests
• Auto-resolve merge conflicts
• Execute end-to-end tests

Day 1 Evening: QA Phase

• Identify areas needing additional testing
• If fixes needed, run additional implementation in relevant worktree
• Final code quality check

Day 2 Morning: Deployment

• Merge to main branch
• Auto-deploy to staging
• Promote to production (as needed)

Part 5: Advanced Techniques and Optimization

5.1 CLAUDE.md Scope Management

In large parallel projects, each worktree may need different development guidelines. The parent's CLAUDE.md is inherited by children, but worktree-specific scopes enable more precise instructions.

# Worktree-specific CLAUDE.md example
/project/wt-feature-auth/CLAUDE.md
 
---
# Auth Module Development Scope
 
## Deadline
 
- 2026-03-30 20:00 JST

5.2 Real-Time Monitoring with Ctrl+T

Press Ctrl+T in Claude Code to display a real-time dashboard for all agents and worktrees.

Display includes:

• Each worktree's branch name
• Each agent's status (running/waiting/complete)
• Task progress bar (completed/total tasks)
• Per-agent error logs
• Resource usage (CPU/memory)

This dashboard is the lifeline of parallel development. Issues can be addressed immediately.

5.3 Error Recovery and Retry Strategies

Parallel development can't stop when one agent fails. Robust recovery mechanisms are essential.

// Retry-enabled agent execution
async function executeWithRetry(task, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await spawnAgent({
        task: task.description,
        worktree: task.worktree,
      }).waitForCompletion();
 
      if (result.success) {
        return result;
      }
    } catch (error) {
      console.log(`Attempt ${attempt}/${maxRetries} failed: ${error}`);
 
      if (attempt < maxRetries) {
        // Exponential backoff
        await sleep(Math.pow(2, attempt) * 1000);
      }
    }
  }
 
  // Handle all retries exhausted
  throw new Error(`Task failed: ${task.description}`);
}

5.4 Performance Tuning

Maximize parallel development speed with these optimizations:

Tuning 1: Worktree Count Optimization

• Too few: low parallelism, long overall time
• Too many: resource contention, each agent slower
• Sweet spot: 70–80% of system cores

Tuning 2: Task Granularity

• Large tasks: lower parallelism, less overhead
• Small tasks: higher parallelism, more scheduling overhead
• Recommended: 10–30 minutes per task

Tuning 3: Minimize Dependencies

• More dependencies = more wait time
• Split into independent tasks where possible

Part 6: Troubleshooting

6.1 Common Issues and Solutions

Issue 1: Merge Conflicts Between Agents

Multiple agents editing the same file cause conflicts. Solutions:

• Define file ownership clearly (each agent owns different files)
• Pre-coordinate areas where conflicts are expected

Issue 2: Deadlock (Circular Dependencies)

Task A depends on Task B, and Task B depends on Task A = infinite wait. Solutions:

• Validate dependency graphs before execution
• Implement automated circular dependency detection

Issue 3: Resource Exhaustion

Spawning 7 agents simultaneously can exhaust memory. Solutions:

• Reduce concurrent agent count
• Schedule large worktrees separately

Issue 4: Orphaned Worktrees

Failed deletions leave ghost worktrees consuming disk space. Solutions:

# List remaining worktrees
git worktree list
 
# Force remove
git worktree remove --force wt-orphaned

6.2 Log Analysis and Debugging

Each worktree's logs are stored at:

/project/wt-feature-auth/.claude-code-logs/
├── 2026-03-30_19-30.log    # Execution log
├── 2026-03-30_19-35.log
└── 2026-03-30_19-40.log

When an agent encounters issues:

# Check logs
tail -f /project/wt-feature-auth/.claude-code-logs/*.log
 
# Grep for errors
grep -i error /project/wt-feature-auth/.claude-code-logs/*.log