DEV Community

brian austin
brian austin

Posted on

Claude Code subagents: run parallel tasks without blocking your main session

#claudecode #ai #programming #productivity

Claude Code subagents: run parallel tasks without blocking your main session

One of the most underused features in Claude Code is the ability to spawn subagents — separate Claude instances that run tasks in parallel while your main session keeps going.

Here's how to use them effectively.

What are subagents?

When Claude Code uses the Task tool, it spawns a new Claude instance with its own context window. This subagent:

  • Has no access to your main session's context
  • Runs in a separate process
  • Returns a result when done
  • Can use all the same tools (Read, Write, Bash, etc.)

This means you can parallelize work that would otherwise block your session.

Basic subagent pattern

Tell Claude explicitly:

Run these 3 tasks in parallel using subagents:
1. Run the full test suite and report failures
2. Check all TypeScript errors in src/
3. Scan for TODO comments in the codebase

Report back when all three complete.
Enter fullscreen mode Exit fullscreen mode

Claude Code will spawn 3 separate Task calls and wait for all to return.

When subagents shine

Long-running analysis 

While I'm working on the auth module, have a subagent:
- Audit all database queries for N+1 problems
- Return a prioritized list with file:line references
Enter fullscreen mode Exit fullscreen mode

Your main session continues. The subagent works independently.

Cross-codebase search 

Use subagents to search these 4 repos in parallel:
- repo-a/src for usage of deprecated API
- repo-b/src for same deprecated API
- repo-c/lib for same deprecated API
- repo-d/services for same deprecated API

Merge the results.
Enter fullscreen mode Exit fullscreen mode

Test generation at scale 

For each file in src/utils/, spawn a subagent to:
1. Read the file
2. Identify untested functions
3. Write tests to tests/utils/<filename>.test.ts

Run all in parallel.
Enter fullscreen mode Exit fullscreen mode

The context isolation problem

Subagents don't share context with your main session. This is both a feature and a limitation.

What subagents can't see:

  • Your CLAUDE.md instructions (unless they're in the project root)
  • Variables or state from your current conversation
  • Files you've opened but haven't saved

Workaround: Pass explicit context in your Task instruction:

Run a subagent with this context:
- We're using PostgreSQL 14 with Drizzle ORM
- Convention: all queries go through src/db/queries/
- Task: find all raw SQL strings that bypass the query layer
Enter fullscreen mode Exit fullscreen mode

Rate limits and subagents

Each subagent makes its own API calls. If you're running 5 parallel subagents, you're consuming 5x the API capacity.

On the standard Claude.ai plan, this hits rate limits fast. You'll see:

Error: rate_limit_exceeded
Enter fullscreen mode Exit fullscreen mode

The fix: point ANTHROPIC_BASE_URL at a proxy that handles the load:

export ANTHROPIC_BASE_URL=https://simplylouie.com/api/proxy
Enter fullscreen mode Exit fullscreen mode

This lets you run as many parallel subagents as your tasks require without hitting Anthropic's per-user rate limits. $2/month at simplylouie.com vs watching your parallel tasks fail mid-run.

Subagent output format

For structured results from subagents, tell Claude the format:

Have each subagent return JSON:
{
  "file": "path/to/file",
  "issues": [{"line": 42, "type": "n+1", "description": "..."}],
  "severity": "high|medium|low"
}
Enter fullscreen mode Exit fullscreen mode

Claude Code will aggregate these into a coherent report.

CLAUDE.md for subagent-heavy workflows

If you use subagents regularly, add to your CLAUDE.md:

## Parallel execution
- Always use subagents for tasks that can run independently
- Pass explicit context: DB type, conventions, file locations
- Format subagent output as JSON for easy aggregation
- Run test suite, type check, and lint in parallel before any PR
Enter fullscreen mode Exit fullscreen mode

Real workflow example

Here's a complete pre-commit check using subagents:

Before I commit, run these in parallel:

Subagent 1: Run `npm test` and return pass/fail + any failure messages
Subagent 2: Run `npx tsc --noEmit` and return any type errors
Subagent 3: Run `npm run lint` and return any lint violations
Subagent 4: Check that no console.log statements exist in src/ (not tests)

When all complete, give me a go/no-go summary.
Enter fullscreen mode Exit fullscreen mode

This takes 30-60 seconds instead of running each check sequentially.

Limitations to know

  • Subagents can't communicate with each other mid-run
  • Max depth is limited (subagents of subagents work but get unwieldy)
  • File write conflicts can happen if two subagents write the same file
  • Each subagent starts fresh — no memory of previous subagent runs

The practical ceiling

For most workflows, 3-5 parallel subagents is the sweet spot. Beyond that, coordination overhead and rate limit pressure outweigh the parallelism gains.

The biggest win is using a single subagent for long-running background tasks (full test suite, dependency audits, large codebase searches) while your main session does focused editing.

That's the pattern that actually changes how fast you work.

Running into rate limits when you spawn multiple subagents? SimplyLouie is $2/month and removes the per-user ceiling — set ANTHROPIC_BASE_URL and your parallel workflows stop failing.

Top comments (0)