Claude Code parallel tasks: how to run multiple agents simultaneously

One of Claude Code's most underused features is its ability to run tasks in parallel using subagents. Instead of waiting for one long task to finish before starting the next, you can spin up multiple agents that work simultaneously.

Here's how it actually works — and the exact patterns that make it useful.

Why parallel matters

Most developers use Claude Code sequentially:

Task 1 → wait → Task 2 → wait → Task 3 → done

With parallel subagents:

Task 1 ┐
Task 2 ├→ all finish → done
Task 3 ┘

For independent tasks, this can cut total time by 60-80%.

The basic pattern

In your CLAUDE.md, you can instruct Claude to use parallel execution:

# Execution Strategy

For independent tasks, spawn parallel subagents rather than executing sequentially.
Use parallel execution when tasks don't share state or write to the same files.

Then in your prompts:

Run these three tasks in parallel:
1. Write unit tests for src/auth.js
2. Write unit tests for src/billing.js  
3. Write unit tests for src/api.js

Claude Code will spawn three subagents, each working independently.

The TodoWrite coordination pattern

For complex parallel work, use the TodoWrite tool to coordinate:

Create a parallel execution plan:
- TodoWrite: mark all independent tasks as parallel
- Spawn subagents for each parallel group
- Collect results when all agents complete
- Run dependent tasks sequentially after

This gives you a visual progress tracker as each agent completes its work.

Real example: parallel test writing

Here's a prompt that reliably triggers parallel execution:

I have 5 service files that all need unit tests:
- src/services/auth.service.js
- src/services/user.service.js
- src/services/billing.service.js
- src/services/email.service.js
- src/services/api.service.js

These services are independent. Write tests for all 5 in parallel.
Each test file should go in tests/ with the same name pattern.

Claude Code recognizes the independence and parallelizes automatically when given explicit permission.

Real example: parallel code review

Review these 4 PRs in parallel and give me a summary of each:
- PR #47: auth refactor (branch: auth-refactor)
- PR #51: new billing endpoints (branch: billing-v2)
- PR #54: rate limiting (branch: rate-limits)
- PR #58: dashboard redesign (branch: dashboard-v2)

For each: check for bugs, security issues, and missing tests.

The parallel subagent architecture

When Claude Code spawns subagents, each gets:

• Its own context window
• Read access to your full codebase
• Tool access (bash, write, read)
• A specific task with clear boundaries

The parent agent coordinates — it waits for all subagents to finish, collects their outputs, and synthesizes a final response.

What works well in parallel

✅ Writing tests for independent modules

✅ Reviewing multiple PRs

✅ Generating documentation for separate functions

✅ Running analysis on different parts of a codebase

✅ Building independent features (different files, no shared state)

What doesn't work in parallel

❌ Tasks that write to the same file

❌ Tasks with sequential dependencies (B requires A's output)

❌ Tasks that modify shared database schema

❌ Tasks that need to coordinate on naming or interfaces

The CLAUDE.md parallel hint

Add this to your CLAUDE.md to encourage parallel execution by default:

# Parallelization

Default to parallel execution for independent tasks.
Before starting multiple tasks, check:
1. Do any tasks share output files? → sequential
2. Does any task require another's output? → sequential  
3. Are all tasks truly independent? → parallel

Spawn subagents explicitly rather than working sequentially.

Measuring the speedup

For a rough benchmark: writing tests for 5 independent files sequentially takes ~15 minutes. In parallel, the same work takes ~4 minutes — the longest single task, not the sum of all tasks.

The speedup is most dramatic when:

• Tasks are roughly equal in complexity
• Each task is self-contained
• You have a clear list of independent work items

Using ANTHROPIC_BASE_URL for parallel agents

If you're running heavy parallel workloads, token costs multiply with each subagent. A flat-rate API proxy can make parallel execution economically viable — SimplyLouie offers Claude access at $2/month with no per-token charges, which makes running 5 parallel agents cost the same as running 1.

The formula: if you run N parallel agents, your token usage multiplies by N. Flat-rate changes the economics entirely.

The bottom line

Parallel subagents are the single biggest productivity unlock in Claude Code that most developers haven't discovered yet.

The key insight: Claude Code doesn't parallelize automatically — you have to explicitly ask for it. Once you build the habit of identifying independent tasks and requesting parallel execution, you'll find it hard to go back to sequential workflows.

Start with your test suite. If you have 10 independent test files to write, that's the perfect parallel task.