NEW: Claude Code Security — research preview →

Parallel Agent Teams

Coordinate multiple Claude Code sessions and background agents to tackle large codebases concurrently

Read time: 14 min

title: "Parallel Agent Teams" description: "Coordinate multiple Claude Code sessions and background agents to tackle large codebases concurrently" section: "Workflows" readTime: "14 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 reduce wall-clock time by 60–80%.

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:

# Terminal 1
git checkout -b agent/auth-refactor
claude "Refactor the auth module in src/auth/ to use the new JWT library. 
Run tests after each file change. Commit when done."
 
# Terminal 2
git checkout -b agent/payment-refactor
claude "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
git checkout -b agent/add-test-coverage
claude "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."

Headless Background Agents

Use --print (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 Task 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 Task tool enables true subagent spawning from within a session.

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:

# 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: Background Agents

Copilot's cloud agents (in GitHub.com) run asynchronously and open PRs:

  1. In GitHub Copilot Chat → "Assign to Copilot" on multiple issues simultaneously
  2. Each issue gets its own PR — fully parallel
  3. Review and merge independently

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

Cursor: Multiple Composer Windows

Cursor allows multiple Composer sessions:

  • Cmd+Shift+I opens a new Composer window
  • Each window has independent context
  • Use @git:branch-name to scope a Composer to a specific branch's files
# Composer Window 1
@git:feature/auth Work only on the auth module. [task]

# Composer Window 2  
@git:feature/payments Work only on the payments module. [task]

Token Budget Management

Parallel agents consume tokens N× faster. Optimize:

# Use --max-turns to cap each agent's conversation length
claude --max-turns 20 "Generate tests for src/utils/string.ts"
 
# Use concise output mode for batch jobs
claude -p --output-format text "..."  # text only, no markdown overhead

Checklist