Parallel Task Execution Across Worktrees

The manual multi-instance pattern

Running multiple Claude Code sessions in parallel requires nothing more than separate terminals. Each worktree operates independently, each terminal runs its own agent instance.

The simplest approach:

# Terminal 1
cd .trees/feature-auth && claude

# Terminal 2
cd .trees/feature-dashboard && claude

# Terminal 3
cd .trees/feature-api && claude

Three terminals, three agents, three independent development streams. Each agent has its own context, its own conversation history, its own file state. Changes in one worktree do not affect the others.

This manual pattern works well for 2-3 parallel sessions when managing terminals by hand. Window management becomes the limiting factor at higher numbers. Tracking which terminal contains which task requires discipline: clear naming, consistent positioning, or a window management tool.

Practical setup:

Terminal multiplexers like tmux or iTerm2 panes keep sessions visible simultaneously. Create named sessions for each worktree:

# Create detached tmux sessions, one per worktree
tmux new-session -d -s auth "cd .trees/feature-auth && claude"
tmux new-session -d -s dashboard "cd .trees/feature-dashboard && claude"

The -d flag creates detached sessions running in the background. Attach to interact with them:

tmux attach -t auth
# Detach with Ctrl-b d, then attach to another
tmux attach -t dashboard

This approach demands manual attention. Each session needs monitoring. Each requires separate context switches to check progress, approve tool use, or provide guidance. Cognitive load scales with session count.

With orchestration tools (covered below), 3-5 parallel sessions become manageable. The research on optimal parallel count from earlier applies here: diminishing returns set in beyond five agents, regardless of tooling.

Custom slash commands for parallel workflows

Claude Code's custom commands streamline parallel setup. Rather than manually creating worktrees and launching sessions, a single command handles initialization.

Create .claude/commands/init-parallel.md:

---
name: init-parallel
description: Set up multiple worktrees for parallel agent execution
argument-hint: <task-name> <count>
---

Create $ARGUMENTS worktrees for parallel development.

For each worktree:
1. Create a new git worktree in .trees/
2. Create a new branch named task/<task-name>-<number>
3. Copy .env and .env.local files
4. Install dependencies
5. Configure unique ports (base 3000 + index × 10)

Report the created worktree paths and branches when complete.

The $ARGUMENTS variable receives parameters passed when invoking the command. Run it with:

/project:init-parallel auth-refactor 3

The agent creates three worktrees, each configured and ready for a parallel session.

For task assignment, create .claude/commands/parallel-tasks.md:

---
name: parallel-tasks
description: Document tasks for parallel worktree execution
argument-hint: <plan-file>
---

Read $ARGUMENTS and create a task file in each worktree under .trees/.

For each worktree, write a .llm/task.md file containing:
1. The specific task assigned to that worktree
2. Success criteria
3. Files likely to be modified
4. Dependencies on other tasks (if any)

This prepares each worktree for independent agent execution.

These commands automate the repetitive setup while keeping human control over task assignment and execution.

Orchestration tools

Tools for managing parallel agent sessions have multiplied. Each takes a different approach to the core problem: running multiple isolated agents without losing track of them.

Claude Squad uses tmux and git worktrees under the hood. Install via Homebrew:

brew install smtg-ai/tap/claude-squad

Launch with:

cs

The terminal interface displays all active sessions. Create new sessions, terminate them, commit changes, pause and resume work. The tool handles worktree creation and tmux session management automatically.

Claude Squad supports auto-accept mode for trusted tasks, allowing agents to proceed without manual approval at each step. Completed work appears as diffs before merging.

Note: The orchestration tool ecosystem is evolving rapidly. Check current documentation for features and installation methods. Tools like Crystal (desktop GUI), CCManager (CLI without tmux dependency), and Container Use (Dagger-based containerization) offer alternative approaches.

Container Use takes isolation further by running each agent in a separate container. Every agent gets its own filesystem, environment, and git branch. The Model Context Protocol (MCP) server integration lets Claude Code invoke containerized execution directly.

The trade-off: container overhead adds startup time and resource consumption. For short tasks, this overhead outweighs the isolation benefit. For longer parallel efforts or when testing untrusted code, containerization provides stronger guarantees than worktrees alone.

Cursor's parallel agents

Cursor 2.0 (released October 2025) supports up to eight parallel AI agents using git worktrees. The IDE manages worktree creation and agent coordination automatically.

Each agent maps to one worktree. Configuration in .cursor/worktrees.json:

{
  "setup-worktree-unix": ["npm ci", "cp .env.example .env"],
  "setup-worktree-windows": ["npm ci", "copy .env.example .env"]
}

Setup commands run when Cursor creates a worktree for a new agent.

One pattern Cursor enables: execute the same prompt across multiple models simultaneously, then compare results. Three agents implementing the same feature provide options to choose from rather than a single outcome to accept or reject.

Limitations apply:

• Maximum 20 worktrees per workspace
• Auto-cleanup removes inactive worktrees after 6 hours
• Language Server Protocol support is limited during agent operations in worktrees

For Claude Code users, Cursor's approach shows where IDE-integrated parallel execution is heading. The concepts translate: multiple agents, isolated worktrees, automated setup, centralized monitoring.

Monitoring and supervision patterns

Parallel execution increases throughput but also increases the monitoring burden. Three agents produce three times the decisions to review, three times the potential errors, three times the context to maintain.

Progress tracking through files:

Create a RESULTS.md file at the worktree root that agents update as they complete tasks:

# Agent Progress - Auth Refactor

## Completed
- [x] Extract auth middleware to separate module
- [x] Add JWT validation

## In Progress
- [ ] Implement refresh token logic

## Blocked
- None

## Changes Made
- src/middleware/auth.ts: Extracted from server.ts
- src/auth/jwt.ts: New file for JWT utilities

Instruct agents to maintain this file. It provides visibility without constant terminal monitoring.

Status dashboard pattern:

For larger parallel efforts, a central task list tracks all worktrees:

# parallel-status.md (in main worktree)

| Worktree | Branch | Status | Last Updated |
|----------|--------|--------|--------------|
| auth | feature/auth | Working | 14:23 |
| dashboard | feature/dashboard | Waiting | 14:21 |
| api | feature/api | Complete | 14:18 |

Check this file to see which agents need attention versus which are progressing autonomously. Update it manually during monitoring sweeps, or instruct agents to update their own rows.

Intervention triggers:

Not every session needs constant watching. Identify when to intervene:

• Agent requests approval: Stop current work, address the request
• Extended silence: 10-15 minutes without visible progress often indicates a stuck state
• Repeated errors: The same error appearing multiple times suggests the agent is looping
• File changes outside scope: Agent modifying unrelated files indicates context drift

For trusted tasks in controlled environments, auto-accept mode reduces intervention frequency. For exploratory or risky work, frequent checking prevents wasted effort.

The reviewer bottleneck:

Parallel agents work faster than humans can review. Three agents completing three features in 30 minutes produce 90 minutes of review work. The efficiency gain shifts from development time to review time.

One approach: use parallel agents for tasks that do not accumulate competing review demands. Research, documentation, proof-of-concept implementations, and low-stakes maintenance parallelize well. Core feature development often requires sequential attention because the review load compounds.

Resource management

Parallel agents consume parallel resources. API rate limits, token budgets, and system resources require attention at scale.

API rate limits:

Claude Code usage limits apply per account, not per session. Three agents sharing an account consume the budget three times faster. The 5-hour session window and token limits documented in Module 2 apply across all concurrent sessions.

Monitor usage with /cost in each session. When approaching limits, prioritize which sessions continue versus which pause.

Token efficiency:

Each worktree can have its own CLAUDE.md file with context specific to that task. Rather than repeating project-wide context, provide focused guidance:

# CLAUDE.md in .trees/feature-auth/

## Task Focus
This worktree handles authentication refactoring only.
Do not modify files outside src/auth/ and src/middleware/.

## Relevant Context
- Current auth implementation uses session-based authentication
- Target: JWT with refresh tokens
- Tests in tests/auth/ must pass

## Constraints
- Maintain backward compatibility with existing session API
- Do not modify database schema

Focused context reduces token consumption and keeps agents on task.

System resources:

Each Claude Code instance consumes memory and CPU for the terminal process and any language servers. Agents running tests or builds compete for system resources.

Stagger resource-intensive operations: one agent runs tests while others write code. Avoid parallel npm install operations on the same machine. Monitor disk space when multiple worktrees have large dependency trees.

For teams running many parallel sessions, dedicated machines or cloud development environments help. GitHub Codespaces, Gitpod, and similar services provide isolated environments with their own resource allocations.

When parallel execution fails

Not every task benefits from parallelization. Some scenarios actively harm productivity.

Tightly-coupled features:

When Task A changes interfaces that Task B consumes, parallel execution produces incompatible code. Complete Task A first. Let Task B work with the new interfaces.

Database schema changes:

Migrations conflict when multiple agents modify schema. Serialize database work. Parallelize application code that uses stable schemas.

Short tasks:

If a task takes 15 minutes, the overhead of worktree setup and context establishment does not justify parallelization. Quick wins execute faster sequentially.

High coordination overhead:

Tasks requiring frequent synchronization, such as shared configuration, interdependent test data, or sequential deployment, gain little from parallel execution. The coordination cost exceeds the parallelization benefit.

A useful heuristic: if tasks can run on separate branches and merge without discussion, they parallelize well. If merging requires careful review, conflict resolution, or behavioral verification, sequential execution is often faster overall.

The next section covers worktree cleanup and management: proper removal, pruning, and automation for maintaining a healthy worktree environment.