title: Parallel Worktree slug: parallel-worktree category: workflow-pattern status: experimental difficulty: advanced tags: [git-worktrees, parallelism, isolation, multi-agent, advanced] prerequisites: [basic-cli-usage, git-advanced, fan-out-fan-in] estimated_time: 20min to learn, setup per project cost_per_use: "$0.50-$5.00 depending on parallelism"

Parallel Worktree

Problem

When multiple agent instances work in the same repository simultaneously, they create file conflicts. One agent's uncommitted changes interfere with another's reads. Git branches alone do not solve this because the working directory is shared. You need full filesystem isolation so each agent operates on its own copy of the code without affecting others.

Solution

Use git worktree to create separate working directories for each sub-agent. Each worktree shares the same Git history but has its own independent filesystem, so agents can work in parallel without conflicts.

Step-by-Step

1. Create worktrees: One per parallel task, each on its own branch.
2. Dispatch agents: Each agent runs in its own worktree directory.
3. Work in parallel: Agents read and write files without interfering.
4. Merge results: Bring branches together via merge or cherry-pick.
5. Clean up: Remove worktrees when done.

When to Use

• Running 3+ agents simultaneously on the same repo
• Tasks that modify overlapping files in different ways
• Large refactors split by module or feature
• CI/CD pipelines that run agent tasks in parallel
• When the Fan-Out Fan-In pattern hits merge conflicts

When NOT to Use

• Tasks that can run sequentially without time pressure
• Repos too large to have multiple worktrees on disk
• When sub-tasks are trivially isolated (separate output files)
• Teams unfamiliar with git worktrees (learn worktrees first)

Example: Claude Code

#!/bin/bash
# parallel-refactor.sh — Refactor 3 modules in parallel using worktrees

REPO_ROOT=$(git rev-parse --toplevel)
BASE_BRANCH=$(git branch --show-current)
MODULES=("auth" "billing" "notifications")

# Step 1: Create worktrees
for module in "${MODULES[@]}"; do
  git worktree add \
    "${REPO_ROOT}/../worktrees/refactor-${module}" \
    -b "refactor/${module}" \
    "$BASE_BRANCH"
done

# Step 2: Dispatch agents in parallel
for module in "${MODULES[@]}"; do
  WORKTREE="${REPO_ROOT}/../worktrees/refactor-${module}"
  claude -p "Refactor the ${module} module in src/${module}/ to use \
    the new BaseService pattern. Follow the example in src/users/service.ts. \
    Run tests after refactoring. Commit your changes." \
    --cwd "$WORKTREE" &
done

# Step 3: Wait for all agents to finish
wait
echo "All agents complete."

# Step 4: Merge results back
git checkout "$BASE_BRANCH"
for module in "${MODULES[@]}"; do
  echo "Merging refactor/${module}..."
  git merge "refactor/${module}" --no-edit
  if [ $? -ne 0 ]; then
    echo "Conflict merging ${module}. Resolve manually."
    break
  fi
done

# Step 5: Clean up worktrees
for module in "${MODULES[@]}"; do
  git worktree remove "${REPO_ROOT}/../worktrees/refactor-${module}"
  git branch -d "refactor/${module}"
done

# Quick two-worktree setup for a single pair of tasks
git worktree add ../wt-frontend -b task/frontend main
git worktree add ../wt-backend -b task/backend main

# Run agents
claude -p "Update the React components in src/components/." --cwd ../wt-frontend &
claude -p "Update the API handlers in src/api/." --cwd ../wt-backend &
wait

# Merge
git merge task/frontend --no-edit
git merge task/backend --no-edit

# Clean up
git worktree remove ../wt-frontend && git branch -d task/frontend
git worktree remove ../wt-backend && git branch -d task/backend

Example: Codex CLI

# Codex with worktrees
MODULES=("auth" "billing" "notifications")
REPO_ROOT=$(git rev-parse --toplevel)

for module in "${MODULES[@]}"; do
  git worktree add "../wt-${module}" -b "refactor/${module}" main
  codex -q "Refactor src/${module}/ to use BaseService pattern. \
    Commit changes." --cwd "../wt-${module}" &
done

wait

# Merge all branches
for module in "${MODULES[@]}"; do
  git merge "refactor/${module}" --no-edit
  git worktree remove "../wt-${module}"
  git branch -d "refactor/${module}"
done

Cost Estimate

Wall-clock time is divided by the number of parallel agents, but total token cost is the same as sequential execution.

Maturity Notes

Status: Experimental. Git worktrees are a mature Git feature, but orchestrating multiple CLI agents across worktrees is still an emerging practice. Key risks: merge conflicts when modules share interfaces, inconsistent changes across worktrees, and disk space for large repos. Mitigate by choosing truly independent modules and including a final consistency-review pass. The --cwd flag support varies by agent tool version — verify it works in your setup before scripting.

Related

• Pattern: Fan-Out Fan-In
• Pattern: Checkpoint Commit
• Module: Agent Teams
• Module: Orchestration Patterns