Run multiple Claude Code agents simultaneously across git worktrees - transform a single developer into a team of AI engineers.

This skill enables parallel AI-assisted development by combining git worktrees (isolated working directories sharing a single .git database) with Claude Code agents (independent Claude sessions or background Task agents). It exploits LLM non-determinism as a feature: running N parallel agents gives you N valid solutions to choose from.

Two modes of operation:

1. Interactive Parallel: Multiple terminal sessions with Claude in separate worktrees
2. Background Orchestration: Main agent delegates to background agents in worktrees, continues working, syncs results when complete

• Parallel Development - Spawn multiple Claude agents working simultaneously on the same task
• Competitive Solutions - Leverage LLM non-determinism to get N different implementations
• Background Orchestration - Delegate work to background agents while continuing main task
• Easy Merging - Compare implementations and merge the best solution
• Resource Efficiency - Worktrees share .git database, saving disk space
• Workflow Scripts - Ready-to-use scripts for spawning, syncing, and cleanup

The easiest way to install this skill is using the Skilz Universal Installer:

# Install Skilz (one-time setup)
curl -fsSL https://raw.githubusercontent.com/SpillwaveSolutions/skilz/main/install.sh | bash

# Install this skill
skilz install SpillwaveSolutions_parallel-worktrees/parallel-worktrees

View on the Skilz Marketplace: parallel-worktrees

Clone directly into your Claude Code skills directory:

# Navigate to your skills directory
cd ~/.claude/skills

# Clone the repository
git clone https://github.com/SpillwaveSolutions/parallel-worktrees.git

After installation, verify the skill is available:

# List installed skills
ls ~/.claude/skills/parallel-worktrees

# Or ask Claude Code
# "List my installed skills"

Claude Code automatically activates this skill when you mention:

• "parallel agents" / "background agents"
• "worktrees" / "agent coordination"
• "subagents" / "parallel tasks"
• "async Claude" / "spawn agents"
• "parallel development" / "multi-agent workflow"

# Create 3 worktrees for a feature
./scripts/spawn-parallel.sh user-dashboard 3

# Output:
#   cd .worktrees/user-dashboard-1 && claude
#   cd .worktrees/user-dashboard-2 && claude
#   cd .worktrees/user-dashboard-3 && claude

Open separate terminals and run Claude in each worktree:

# Terminal 1
cd .worktrees/user-dashboard-1 && claude

# Terminal 2
cd .worktrees/user-dashboard-2 && claude

# Terminal 3
cd .worktrees/user-dashboard-3 && claude

In each session, provide the same prompt. Each Claude instance works independently with its own context window.

# Compare implementations
cd .worktrees/user-dashboard-1 && git diff main
cd .worktrees/user-dashboard-2 && git diff main

# Merge the winner
git checkout main
git merge user-dashboard-2

./scripts/cleanup-worktrees.sh user-dashboard --delete-branches

See references/workflow-patterns.md for detailed examples.

Creates parallel git worktrees for multi-agent development.

./scripts/spawn-parallel.sh <feature-name> [num-agents] [base-branch]

Example:

./scripts/spawn-parallel.sh auth-refactor 4 develop

Removes parallel worktrees and optionally their branches.

./scripts/cleanup-worktrees.sh <feature-name> [--delete-branches]

• Detects uncommitted changes and prompts before force-removing
• Prunes stale worktree metadata
• Shows remaining worktrees when done

Reviews and merges completed worktree work back to main.

./scripts/sync-worktrees.sh [--status|--merge|--interactive]

Example workflow:

# Check what's ready
./scripts/sync-worktrees.sh --status

# Interactively review and merge
./scripts/sync-worktrees.sh --interactive

Use Claude Code's native background agents (Task tool with run_in_background: true) combined with worktrees to delegate work while you continue on your main task.

Main Worktree (Orchestrator)
├── .agent-status/           # Status tracking (JSON files)
│   ├── task-api.json        # {"status": "COMPLETE", "summary": "..."}
│   └── task-ui.json
└── .worktrees/
    ├── task-api/            # Background agent 1's workspace
    │   └── RESULTS.md       # Agent writes summary here
    └── task-ui/             # Background agent 2's workspace
        └── RESULTS.md

1. Prepare worktrees for each parallel task:

   git worktree add .worktrees/task-api -b task-api main
   git worktree add .worktrees/task-ui -b task-ui main

2. Launch background agents via Task tool:

   • Each agent works in its assigned worktree
   • Agent writes RESULTS.md when complete
   • Agent updates .agent-status/<task>.json with status

3. Continue main work while agents run in background

4. Monitor progress: Check .agent-status/*.json or use TaskOutput

5. Sync results when complete:

   ./scripts/sync-worktrees.sh --interactive

Background agents should write status to .agent-status/<task-name>.json:

{
  "status": "COMPLETE",
  "started": "2024-01-15T10:30:00Z",
  "completed": "2024-01-15T10:45:00Z",
  "summary": "Implemented 5 endpoints, 12 tests passing",
  "files_changed": ["src/api/users.ts", "tests/api.test.ts"]
}

Status values: RUNNING, COMPLETE, FAILED, BLOCKED

When spawning background agents, include:

## Task: [Task Name]
Work in `.worktrees/[task-name]/`

### Requirements
[Specific requirements]

### On Completion
1. Write summary to `RESULTS.md`
2. Commit: `git add -A && git commit -m "[task]: [summary]"`
3. Update: `../.agent-status/[task].json` with status: "COMPLETE"

Use parallel worktrees when:

• Multiple valid solutions exist (UI, algorithms)
• Complex tasks have failure risk (run 3, pick winner)
• Clear detailed plan exists for independent execution
• Features don't overlap in file modifications

Use sequential when:

• Critical refactors requiring consistency
• Tightly coupled changes to same files
• Merge conflicts would cost more than parallelism saves

• Token usage: ~15x higher with multi-agent workflows
• Subagent nesting: Subagents cannot spawn other subagents
• Context isolation: Each subagent starts fresh, needs codebase orientation
• Subscription limits: Factor token consumption into your plan

parallel-worktrees/
├── README.md                # This file
├── SKILL.md                 # Skill definition and documentation
├── scripts/
│   ├── spawn-parallel.sh    # Create parallel worktrees
│   ├── cleanup-worktrees.sh # Remove worktrees
│   └── sync-worktrees.sh    # Merge completed work
└── references/
    └── workflow-patterns.md # Detailed pattern documentation

# Create worktree with new branch
git worktree add .worktrees/feature-auth -b feature/auth main

# List all worktrees
git worktree list

# Remove worktree
git worktree remove .worktrees/feature-auth

# Force remove (uncommitted changes)
git worktree remove --force .worktrees/feature-auth

# Clean stale metadata
git worktree prune

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This skill is provided under the MIT License. See LICENSE for details.

For issues, questions, or suggestions:

• Open an issue on GitHub
• Consult the documentation in SKILL.md and references/

Made with care for parallel AI development