DEV Community

brian austin
brian austin

Posted on

Claude Code parallel subagents: how to run multiple AI tasks simultaneously

#claude #ai #productivity #programming

Claude Code parallel subagents: how to run multiple AI tasks simultaneously

One of the most underused features in Claude Code is the ability to spin up multiple subagents and run them in parallel. Most developers use Claude Code sequentially — one task, wait, next task. But Claude Code supports true parallel execution that can cut your workflow time by 60-80%.

Here's the pattern that changed how I use it.

The sequential problem

Typical Claude Code session:

> Write tests for auth.js
[waits 30 seconds]
> Write tests for billing.js  
[waits 30 seconds]
> Write tests for api.js
[waits 30 seconds]
Enter fullscreen mode Exit fullscreen mode

Total: 90 seconds, done one at a time. This is wasteful — there's no reason these can't run simultaneously.

The parallel subagent pattern

In your CLAUDE.md, add a task decomposition instruction:

# Task Execution

For tasks that can be parallelized (multiple independent files, multiple tests,
multiple research queries), always:
1. Decompose the task into independent subtasks
2. Launch subtasks as parallel subagents using the Task tool
3. Aggregate results after all subagents complete

Never run sequentially what can run in parallel.
Enter fullscreen mode Exit fullscreen mode

Now when you ask Claude Code to write tests for multiple files, it will automatically parallelize.

Real example: parallel test generation

Prompt:

Write comprehensive tests for auth.js, billing.js, and api.js
Enter fullscreen mode Exit fullscreen mode

With parallel subagents enabled, Claude Code will:

  1. Launch subagent 1 → auth.js tests
  2. Launch subagent 2 → billing.js tests
  3. Launch subagent 3 → api.js tests
  4. All three run simultaneously
  5. Results aggregated into a single response

Time: ~30 seconds instead of ~90 seconds.

The slash command version

Create .claude/commands/parallel-test.md:

Run tests in parallel for the following files: $ARGUMENTS

For each file:
1. Spawn a subagent using the Task tool
2. Each subagent should: read the file, understand the exported functions, write tests
3. Do NOT run these sequentially — launch all subagents before waiting for results
4. Return all test files when all subagents complete
Enter fullscreen mode Exit fullscreen mode

Usage:

/parallel-test src/auth.js src/billing.js src/api.js
Enter fullscreen mode Exit fullscreen mode

Research parallelization

This pattern is even more powerful for research tasks:

# In CLAUDE.md

## Research tasks
When asked to research multiple topics, use parallel subagents:
- Subagent 1: research topic A
- Subagent 2: research topic B
- Subagent 3: research topic C
Merge findings before responding.
Enter fullscreen mode Exit fullscreen mode

Prompt:

Research the tradeoffs between PostgreSQL, MySQL, and SQLite for my use case
Enter fullscreen mode Exit fullscreen mode

Result: Three subagents research each database simultaneously, then compare results. Much faster than sequential research.

The settings.json configuration

To make subagents more powerful, configure them in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(*)",
      "Read(*)",
      "Write(*)"
    ]
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.simplylouie.com"
  }
}
Enter fullscreen mode Exit fullscreen mode

The ANTHROPIC_BASE_URL setting routes all subagent calls through a single API endpoint. This matters for cost: if you run 10 subagents per session, your API costs multiply by 10x.

That's why I switched to SimplyLouie — a flat-rate Claude API proxy at $2/month. No matter how many parallel subagents I spin up, the cost doesn't change.

Coordination patterns

Fan-out / fan-in 

# CLAUDE.md

## Code review pattern
When reviewing a PR:
1. Fan out: spawn one subagent per changed file
2. Each subagent reviews its file independently
3. Fan in: aggregate all reviews, identify cross-file issues
4. Final output: unified review with file-level + cross-file findings
Enter fullscreen mode Exit fullscreen mode

Pipeline pattern 

## Data pipeline tasks
For multi-stage transformations:
1. Stage 1 subagents: fetch and validate data (parallel)
2. Stage 2 subagents: transform data (parallel, after stage 1)
3. Stage 3: aggregate and output
Enter fullscreen mode Exit fullscreen mode

Race pattern 

## When multiple approaches exist
For problems with multiple valid solutions:
1. Spawn one subagent per approach
2. Each implements their approach
3. Compare results and pick the best
Enter fullscreen mode Exit fullscreen mode

This is particularly useful for "what's the best way to implement X" questions — instead of debating, just try multiple approaches in parallel.

Debugging parallel subagents

If subagents aren't running in parallel, check:

  1. Task tool permissions: Make sure Task is in your allowed tools
  2. Explicit instruction: Claude needs to be told to use Task tool for subagents
  3. CLAUDE.md clarity: The parallelization instruction must be explicit

Add this diagnostic to your CLAUDE.md:

## Subagent debugging
When in doubt about parallelization, print your execution plan before starting:
"I will run N subagents in parallel for: [task list]"
This confirms parallel execution before it starts.
Enter fullscreen mode Exit fullscreen mode

The cost math

Parallel subagents means more API calls. On pay-per-token pricing:

  • 3 parallel subagents = 3x the tokens = 3x the cost
  • 10 parallel subagents = 10x the tokens = 10x the cost

This is why flat-rate pricing matters. At $2/month via SimplyLouie, you can run unlimited parallel subagents without watching the meter.

Setup:

# One-line setup for all Claude Code sessions
echo 'export ANTHROPIC_BASE_URL=https://api.simplylouie.com' >> ~/.zshrc
source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

Now all your parallel subagent sessions route through the flat-rate proxy.

Summary

Pattern Use case Speed gain
Fan-out/in Multi-file review 3-10x
Pipeline Multi-stage transforms 2-5x
Race Multiple approaches subjective
Research Multi-topic research 3-8x

The key insight: Claude Code already supports parallel subagents natively. You just need to tell it to use them via CLAUDE.md instructions and the Task tool.

Start with the CLAUDE.md snippet above and see how much faster your sessions get.

Using Claude Code with parallel subagents on pay-per-token? Check out SimplyLouie — flat-rate API at $2/month so parallel runs don't spike your bill.

Top comments (0)