How to Implement Parallelization Using Git Worktrees with Claude Code: A Complete Guide

Claude Code supports parallel execution through Git worktrees, which create isolated working directories that share the same object database, allowing multiple agents to edit, test, and commit concurrently without conflicts.

The affaan-m/everything-claude-code repository demonstrates how to safely run multiple Claude instances simultaneously using Git worktrees. This approach enables high-throughput parallelization while maintaining isolation between agents, each working in their own checkout while sharing the same repository history.

Architectural Overview of Worktree-Based Parallelization

Git worktrees provide the foundation for safe parallel execution in Claude Code by combining isolation with efficiency.

Isolation Per Agent

Every Claude instance launches inside its own worktree. Because each worktree maintains its own HEAD, branch, and working directory, operations such as committing, branching, or resetting do not affect other agents. This isolation prevents conflicts when multiple AI agents modify the same codebase simultaneously.

Shared Repository Metadata

All worktrees reference the same underlying .git directory and object database. This means history and objects are stored only once, making parallel execution disk-efficient and fast. According to the source code, this architecture is critical for the coordination layer implemented in scripts/orchestrate-worktrees.js.

Coordination Layer

The scripts/orchestrate-worktrees.js script builds a plan that:

1. Creates required worktrees via git worktree add -b
2. Checks out dedicated branches for each agent
3. Copies seed files to appropriate locations
4. Launches a tmux session where each pane runs a Claude task

The orchestrator implements buildOrchestrationPlan, materializePlan, and executePlan functions (defined in scripts/lib/tmux-worktree-orchestrator.js) to manage this workflow.

Session Metadata Tracking

When a Claude session starts, it records the current worktree path in session files. The tests in tests/hooks/hooks.test.js verify that generated session files contain a **Worktree:** header, enabling commands like claude rollback to target the correct checkout. The detection logic is validated in tests/hooks/detect-project-worktree.test.js, ensuring Claude correctly identifies worktree contexts even when .git is a file rather than a directory.

Creating Your First Worktree for Claude Code

To begin parallelization, create a worktree pointing to a feature branch:

git worktree add ../feature-auth feature-auth

This command creates a new directory at ../feature-auth containing a fresh checkout of the feature-auth branch. As noted in the-shortform-guide.md, this pattern maps each worktree to a separate Claude instance while sharing the same repository history.

For a concrete example of creating multiple worktrees for concurrent work, see the-longform-guide.md, which demonstrates setting up three parallel worktrees for distinct feature branches.

Orchestrating Multiple Worktrees with the CLI

The scripts/orchestrate-worktrees.js CLI reads a JSON plan that defines your parallel workflow. Here is an example plan.json:

{
  "sessionName": "parallel-clone",
  "repoRoot": ".",
  "coordinationDir": ".claude/plan",
  "workerPlans": [
    {
      "workerName": "auth-agent",
      "branchName": "feature-auth",
      "worktreePath": "../worktrees/auth",
      "seedPaths": ["scripts/orchestrate-worktrees.js"],
      "taskFilePath": ".claude/tasks/auth.task",
      "launchCommand": "codex exec --cwd {worktree_path} --task-file {task_file}"
    },
    {
      "workerName": "payments-agent",
      "branchName": "feature-payments",
      "worktreePath": "../worktrees/payments",
      "seedPaths": ["scripts/orchestrate-worktrees.js"],
      "taskFilePath": ".claude/tasks/payments.task",
      "launchCommand": "codex exec --cwd {worktree_path} --task-file {task_file}"
    }
  ]
}

To preview the plan without executing:

node scripts/orchestrate-worktrees.js plan.json

The printDryRun function (lines 45-66 in scripts/orchestrate-worktrees.js) outputs a JSON preview of the planned operations, showing which worktrees will be created and which branches will be checked out.

Executing Parallel Claude Sessions

To materialize the worktrees and launch parallel agents:

node scripts/orchestrate-worktrees.js plan.json --execute

The executePlan function (lines 91-96 in scripts/orchestrate-worktrees.js) handles this logic by:

1. Creating worktrees using git worktree add -b
2. Writing coordination files to the .claude/plan directory
3. Launching a tmux session with one pane per worktree
4. Running the specified launch command in each pane

This approach is recommended in skills/dmux-workflows/SKILL.md for file-conflict-prone parallel workflows where isolation is critical.

Verifying Worktree Detection and Metadata

When Claude starts inside a worktree, the session file includes metadata identifying the checkout location. According to tests/hooks/hooks.test.js (line 547), session files contain entries like:

**Worktree:** /tmp/ecc-worktree

The test suite in tests/lib/tmux-worktree-orchestrator.test.js validates that the orchestrator creates worktrees, branches, and tmux commands as expected, ensuring the parallelization infrastructure works correctly before agents begin work.

Summary

• Git worktrees provide isolated working directories that share the same .git object database, making them ideal for parallel Claude Code execution.
• The scripts/orchestrate-worktrees.js CLI automates worktree creation, branch management, and tmux session orchestration.
• Each agent runs in its own worktree with independent HEAD state, preventing conflicts during concurrent editing and committing.
• Session metadata recorded in worktree-specific files enables precise targeting of rollback and other commands.
• The affaan-m/everything-claude-code repository provides comprehensive tests in tests/hooks/ and tests/lib/ to verify worktree detection and orchestration logic.

Frequently Asked Questions

What is a Git worktree and how does it differ from cloning the repository?

A Git worktree is a linked working directory that shares the same underlying .git object database with the main repository. Unlike a full clone, which duplicates the entire .git directory, a worktree only creates a new working directory and index while referencing existing objects. This makes worktrees extremely space-efficient for parallelization, as demonstrated in the Claude Code architecture where multiple agents share history while maintaining isolated checkouts.

How does the orchestrator script handle branch creation?

The scripts/orchestrate-worktrees.js orchestrator uses the git worktree add -b flag to automatically create new branches when setting up worktrees. As defined in the plan.json schema, each worker specifies a branchName that the orchestrator creates during the materialization phase. If the branch already exists, Git checks out the existing branch instead; the script handles both scenarios in the materializePlan function within scripts/lib/tmux-worktree-orchestrator.js.

Can worktrees be used with existing branches or only new ones?

Worktrees support both existing and new branches. When using git worktree add, you can reference an existing branch name to check it out, or use the -b flag to create a new branch from the current HEAD. The Claude Code orchestrator specifically leverages the -b flag in its implementation to ensure each parallel agent starts with a clean branch state, though the underlying Git commands support either approach depending on your workflow requirements.

How does Claude Code track which worktree a session belongs to?

Claude Code tracks worktree association through session metadata files. When a session initializes, the hooks system (tested in tests/hooks/hooks.test.js) records the absolute worktree path in a header format: **Worktree:** /path/to/worktree. This metadata allows subsequent commands like claude rollback to identify and target the correct working directory, even when the .git entry is a pointer file rather than a directory, as validated by tests/hooks/detect-project-worktree.test.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}