Parallel Task Execution

Claude Code can execute multiple independent tool calls in a single response. This dramatically reduces wall-clock time for tasks that do not depend on each other.

When to Use

• Multiple files need to be read, searched, or analyzed independently
• User wants to speed up a multi-step workflow
• Several subagents can investigate different aspects simultaneously
• Independent operations (read + grep + glob) can run concurrently
• User asks about fan-out/fan-in or parallel execution

Core Patterns

Identifying Independent Operations

Two operations are independent when neither needs the other's result. Test by asking: "Can I start operation B without knowing the result of operation A?"

# INDEPENDENT (run in parallel):
- Read file A and Read file B
- Grep for pattern X and Grep for pattern Y
- Analyze auth module and Analyze database module

# DEPENDENT (run sequentially):
- Find the config file, THEN read it
- Read the test file, THEN modify it based on contents
- Get the function signature, THEN find all call sites

Parallel Tool Calls

Make multiple tool calls in a single response block:

# Single response with 3 parallel calls:

Call 1 - Read:
  file_path: "src/auth/middleware.ts"

Call 2 - Read:
  file_path: "src/auth/tokens.ts"

Call 3 - Read:
  file_path: "src/auth/permissions.ts"

All three files are read concurrently. Results arrive together for synthesis.

Fan-Out with Subagents

Launch multiple Agent tool calls for independent investigations:

# Fan-out: 3 parallel subagents

Agent 1:
  prompt: "Analyze all React components in src/components/
           for accessibility issues (missing aria labels,
           no keyboard handlers). Report findings as a list."

Agent 2:
  prompt: "Check all API routes in src/api/ for proper
           error handling. Report which routes lack try/catch
           or return generic error messages."

Agent 3:
  prompt: "Review all database queries in src/db/
           for N+1 query problems. Report file paths and
           the specific query patterns."

Fan-In: Synthesizing Results

After parallel calls complete, synthesize in the next response:

# Step 1: Parallel fan-out (3 Agent calls)
# Step 2: All results arrive
# Step 3: Synthesize

"Based on the three analyses:
 - Accessibility: 4 components need aria labels (Agent 1)
 - Error handling: 2 routes missing try/catch (Agent 2)
 - Database: 1 N+1 query in user-posts loader (Agent 3)

 Priority order: Database N+1 > Error handling > Accessibility"

Mixed Parallel Operations

Combine different tool types in a single parallel batch:

# All independent, all in parallel:

Call 1 - Glob:
  pattern: "src/**/*.test.ts"

Call 2 - Grep:
  pattern: "TODO|FIXME|HACK"
  path: "src/"

Call 3 - Read:
  file_path: "package.json"

Call 4 - Bash:
  command: "git log --oneline -10"

Sequential Dependencies with Parallel Branches

When some steps depend on others but have parallel sub-branches:

# Step 1 (sequential): Read the config to understand the project
Read: "tsconfig.json"

# Step 2 (parallel, depends on Step 1):
# After reading tsconfig, these are independent:
Grep: pattern "import.*from" in src/    # Find all imports
Glob: "src/**/*.d.ts"                   # Find type declarations
Bash: "npx tsc --noEmit 2>&1 | wc -l"  # Count type errors

Background Execution for Long Tasks

Use

run_in_background

Bash:
  command: "npm run test:coverage"
  run_in_background: true

# Continue working on other things while tests run.
# You will be notified when the background task completes.

Parallel File Creation

When creating multiple independent files:

# All independent, all in parallel:

Write: "src/utils/format.ts"
  content: "..."

Write: "src/utils/validate.ts"
  content: "..."

Write: "src/utils/transform.ts"
  content: "..."

Anti-Patterns

• Parallelizing dependent operations: Reading a file and then editing it based on contents must be sequential. Making these parallel causes the edit to use stale or missing data.
• Too many parallel calls: Launching 20 subagents simultaneously can overwhelm the system. Keep parallel batches to 3-5 concurrent operations for stability.
• Ignoring partial failures: When one of several parallel operations fails, do not ignore it. Address the failure before proceeding with synthesis.
• Serializing independent work: Running 5 independent file reads one after another wastes time. If they do not depend on each other, run them in parallel.
• Using parallel agents for tiny tasks: Do not launch a subagent to read a single file. Use the Read tool directly. Subagents have overhead and are only worth it for multi-step investigations.

Quick Reference

run_in_background: true

Independence test: "Can B start without A's result?" If yes, parallelize. Batch size: 3-5 concurrent operations is the sweet spot. Synthesis: Always dedicate a response to combining parallel results.