title: "Parallel Agent Teams" description: "Coordinate multiple Claude Code sessions and background agents to tackle large codebases concurrently" section: "Workflows" readTime: "18 min"

Parallel Agent Teams

A single AI agent works sequentially. An agent team works concurrently — multiple agents tackle independent workstreams simultaneously, then merge. For large refactors, multi-service migrations, or test generation across a big codebase, parallelization can substantially cut wall-clock time — at the cost of proportionally more tokens.

Claude Code offers several levels of parallelism, from lightest to heaviest:

When to Parallelize

Good candidates for parallel agents:

• Generating tests for multiple independent modules
• Migrating several microservices to a new API version simultaneously
• Writing documentation for different sections of a codebase
• Running security audits on separate packages in a monorepo
• Implementing independent features on separate branches

Keep these sequential:

• Tasks with shared state (same file, same database schema)
• Refactors where Step B depends on Step A's output
• Anything that requires a human review gate between steps

Architecture: Git Branches as Agent Lanes

The cleanest parallel pattern uses branches to isolate each agent's work:

main
├── agent/auth-service      ← Agent 1: auth migration
├── agent/payment-service   ← Agent 2: payment migration  
├── agent/notifications     ← Agent 3: notification service
└── agent/test-generation   ← Agent 4: test coverage

Each agent operates on its own branch. You review and merge each one independently.

Claude Code: Multiple Terminal Sessions

Basic Pattern

Open multiple terminals — each runs an independent Claude session. Don't run several agents on different branches in the same checkout: git checkout switches the files under every session at once. Use --worktree (-w), which starts Claude in an isolated git worktree at <repo>/.claude/worktrees/<name>:

# Terminal 1
claude -w auth-refactor "Refactor the auth module in src/auth/ to use the new JWT library. 
Run tests after each file change. Commit when done."
 
# Terminal 2
claude -w payment-refactor "Refactor the payment module in src/payment/ to use the new Stripe SDK v5.
Run tests after each file change. Commit when done."
 
# Terminal 3
claude -w add-test-coverage "Generate Jest tests for all files in src/utils/ that currently have 
less than 60% coverage. Use npm run test:coverage to check. Commit when done."

Add --tmux to open each worktree session in its own tmux session. Without -w, the manual equivalent is git worktree add ../auth-refactor -b agent/auth-refactor and running claude inside that directory.

Headless Background Agents

Use --print / -p (non-interactive) to run agents that don't need your attention:

# Run 4 agents in background, log output to files
claude -p "Generate OpenAPI docs for src/routes/users.ts" > docs/users.md &
claude -p "Generate OpenAPI docs for src/routes/orders.ts" > docs/orders.md &
claude -p "Generate OpenAPI docs for src/routes/products.ts" > docs/products.md &
claude -p "Generate OpenAPI docs for src/routes/auth.ts" > docs/auth.md &
 
# Wait for all to complete
wait
echo "All agents done"

Orchestrator Pattern

One "coordinator" agent spawns and monitors sub-agents:

claude "You are the orchestrator for a codebase migration to TypeScript strict mode.
Your job:
1. List all .ts files with @ts-ignore comments using: grep -r '@ts-ignore' src/ --include='*.ts' -l
2. For each file found, use the Agent tool to spawn a subagent that removes the @ts-ignore 
   and fixes the underlying type error
3. After all subagents complete, run: npm run type-check
4. Report which files were fixed and which still have issues"

Claude Code's Agent tool (called Task before v2.1.63) enables true subagent spawning from within a session. Subagents can run in the background, and a subagent definition with isolation: worktree runs in its own temporary worktree so parallel edits don't collide. See Subagents.

For large mechanical changes, the bundled /batch skill does this orchestration for you: /batch migrate src/ from JavaScript to TypeScript researches the codebase, proposes 5–30 independent units for your approval, then runs one background subagent per unit in its own worktree.

Claude Code Agent Teams (Experimental)

Agent teams coordinate multiple Claude Code instances: one session is the team lead, the others are teammates, each with its own context window. Unlike subagents, which only report back to the caller, teammates share a task list and message each other directly — and you can talk to any teammate without going through the lead.

Enable

Agent teams are disabled by default. Set the environment variable in your shell or in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Spawning teammates requires an interactive session — in -p mode (and the Agent SDK), Claude runs ordinary subagents instead.

Start a Team

Describe the task and the teammates you want in natural language:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

You can name the model ("Use Sonnet for each teammate") or reuse a subagent definition as a role: "Spawn a teammate using the security-reviewer agent type to audit the auth module." Teammates load CLAUDE.md, MCP servers, and skills like a normal session, but not the lead's conversation history — put task-specific context in the spawn prompt.

Display Modes and Controls

Set "teammateMode" in ~/.claude/settings.json, or pass claude --teammate-mode auto for one session. Split panes aren't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

Coordination Features

• Shared task list: tasks are pending, in progress, or completed, and can depend on other tasks. The lead assigns tasks, or teammates self-claim the next unblocked one (file locking prevents double-claims).
• Plan first: put the lead in plan mode before spawning, and teammates work read-only until their plan is approved.
• Quality gates via hooks: TeammateIdle (exit code 2 keeps a teammate working), TaskCreated and TaskCompleted (exit code 2 blocks the action and sends feedback).
• Shutdown: "Ask the researcher teammate to shut down." Team directories are cleaned up when the session ends.

Limitations and Costs

• Token usage scales roughly linearly with the number of active teammates. Start with 3–5 teammates.
• One team per session; teammates can't spawn their own teammates; the lead is fixed for the session.
• /resume and /rewind don't restore in-process teammates.
• Teammate permission prompts appear in the lead session — pre-approve common operations to reduce interruptions.
• Two teammates editing the same file will overwrite each other. Give each teammate its own set of files.

Coordination Rules

Set ground rules to prevent agents from stomping on each other:

# AGENT-RULES.md
## Parallel Agent Rules
 
- Each agent works ONLY on its assigned module (listed at top of PLAN.md)
- Never modify shared files: package.json, tsconfig.json, prisma/schema.prisma
- Always branch from main before starting
- Commit message prefix: "agent/<module>: <description>"
- If you need a shared utility that doesn't exist, create it in src/shared/ 
  and note it in SHARED-CHANGES.md for other agents to review

Reference this file in each agent's starting prompt:

claude "Read AGENT-RULES.md first. Then: [your task]"

Merging Agent Output

After all agents complete (branch names below are illustrative; run git worktree list and git branch to see what your sessions actually created):

# Review each branch
git log --oneline main..agent/auth-refactor
git diff main..agent/auth-refactor
 
# Merge in dependency order (least coupled first)
git checkout main
git merge --no-ff agent/add-test-coverage
git merge --no-ff agent/auth-refactor
git merge --no-ff agent/payment-refactor
 
# Resolve any conflicts
# Run full test suite
npm test

Automated Merge Check

# Check if branches can be merged cleanly
for branch in agent/auth-refactor agent/payment-refactor agent/notifications; do
  git checkout main
  git merge --no-commit --no-ff $branch 2>/dev/null
  if [ $? -eq 0 ]; then
    echo "✓ $branch: clean merge"
    git merge --abort 2>/dev/null
  else
    echo "✗ $branch: conflicts detected"
    git merge --abort
  fi
done

GitHub Copilot: Cloud Agent

Copilot cloud agent (formerly Copilot coding agent) runs asynchronously on GitHub and opens PRs:

1. On GitHub.com, open an issue → Assignees → select Copilot. Repeat for each issue you want worked on in parallel (or start sessions from the repository's Agents tab)
2. Copilot opens a pull request for each assigned issue and requests your review when it finishes
3. Review and merge independently

Good for: bug fixes, documentation, simple feature additions across the repo.

Cursor: Parallel Agents

Cursor's Composer was merged into Agent, which can run several sessions in parallel:

• Run local agents in isolated git worktrees so each task gets its own files and changes (built into the Agents Window; in the editor, use the /worktree and /apply-worktree commands)
• Hand longer tasks to Cloud Agents (formerly Background Agents), which run in their own cloud VMs and branches
• Open the Agents Window (Command Palette → "Open Agents Window") to run and monitor them
• Scope each agent explicitly in the prompt (folder, files) so sessions don't overlap

# Agent 1
Work only on the auth module in src/auth/. [task]

# Agent 2
Work only on the payments module in src/payments/. [task]

Token Budget Management

Parallel agents consume tokens N× faster. Optimize:

# Use --max-turns to cap each agent's agentic turns (print mode only)
claude -p --max-turns 20 "Generate tests for src/utils/string.ts"
 
# Cap estimated spend per agent (print mode only)
claude -p --max-budget-usd 5.00 "Generate tests for src/utils/date.ts"
 
# Use a cheaper model for routine parallel work
claude -p --model sonnet "Generate OpenAPI docs for src/routes/users.ts"

Checklist