Claude Code Multi-Agent Patterns

How to use Claude Code's multi-agent capabilities: spawn subagents for parallel work, use the Agent tool, run background tasks, and coordinate multiple Claude instances.

Claude Code can coordinate multiple agents for complex tasks. This guide covers the patterns that actually work and when parallelism helps vs hurts.

When to parallelize

Parallel subagents via the Agent tool

# In a Claude Code session, Claude can use the Agent tool to dispatch
# parallel subagents. Example prompt that triggers this:

"Simultaneously:
1. Find all API endpoints in src/routes/ and list their auth requirements
2. Check tests/ for any tests that mock the database instead of using real queries
3. Read CLAUDE.md and summarize the architecture

Report all three results back."

# Claude Code dispatches three Agent tool calls in one response.
# Each subagent runs independently (separate context, same tool access).
# Results arrive as each subagent completes.

Background one-shot tasks

# Non-interactive mode in background:
nohup claude --print   "Review all Python files in src/ for security issues. Output a markdown report."   --allowedTools "Read,Grep,Glob"   > security-review.md 2>&1 &

echo "Review running in background (PID $!). Output → security-review.md"

# Check progress:
tail -f security-review.md

# Pipe multiple inputs:
for file in src/routers/*.py; do
  echo "=== $file ===" >> review.md
  claude --print "Review $file for bugs and security issues"     --allowedTools "Read" >> review.md
done

Multi-agent branch workflow

# Pattern: multiple Claude Code instances on separate git branches
# useful for large features where work can truly be parallelized

# Terminal 1 — Agent A works on the API layer:
git checkout -b feature/api-layer
claude "Implement the REST endpoints for user management as described in CLAUDE.md"

# Terminal 2 — Agent B works on tests (against stable main):
git checkout -b feature/api-tests
claude "Write integration tests for the user management endpoints (spec in docs/api-spec.md)"

# After both complete:
git checkout main
git merge feature/api-layer
git merge feature/api-tests  # resolve any conflicts

# Tip: give agents non-overlapping file sets to minimize conflicts.
# CLAUDE.md in each branch should note what the other branch is doing.

Orchestrator + worker pattern

# One "orchestrator" Claude session plans and delegates;
# workers (--print mode) execute specific sub-tasks.

# Orchestrator decides the plan, then calls workers:
PLAN=$(claude --print "Break down the auth refactor into 5 independent subtasks"   --allowedTools "Read,Grep,Glob")

echo "$PLAN" | while IFS= read -r task; do
  [[ -z "$task" ]] && continue
  echo "Running task: $task"
  claude --print "$task" --allowedTools "Read,Edit,Write,Bash(pytest*)"     >> task-results.md
done

Scoping subagents to safe operations

# When spawning background agents, limit their blast radius:

# Read-only research agent:
claude --print "Find all places in the codebase that call external APIs"   --allowedTools "Read,Grep,Glob"

# Limited write agent (only touches test files):
claude --print "Write unit tests for src/utils/auth.py"   --allowedTools "Read,Grep,Write(tests/**),Bash(pytest tests/unit/)"

# The --allowedTools glob Edit(src/**) limits edits to src/ only.
# Bash(pytest*) limits shell access to pytest invocations.

For context management in long multi-step sessions, see Claude Code context window guide. For hook-based coordination, see Claude Code hooks tutorial.

Frequently asked questions

Free tools

More examples