Claude Code Subagents: Run 5 Tasks in Parallel Without Losing Context

Claude Code's Agent tool lets you spawn subagents mid-session. Each runs independently, returns a result, and doesn't pollute your main context window. Here's how to use it correctly — and the failure mode that costs you everything.

The Pattern

Agent({
  description: "Audit auth middleware for security issues",
  prompt: "Read src/middleware/auth.ts and list any security vulnerabilities. Report in under 200 words."
})

That's it. The subagent spins up with its own context window, does the work, and returns a result. Your main session sees only the summary.

Why It Matters

On a 50K-token task, if you run 5 subtasks sequentially in one session, you spend 250K tokens total and your context fills with tool outputs. With 5 subagents in parallel, you spend ~50K tokens in the main session (coordinating + receiving summaries), and 250K tokens distributed across separate subagent windows that close after returning results.

The math: parallel subagents reduce main context growth by ~80% on decomposable tasks.

Running Tasks in Parallel

To run subagents in parallel, send multiple Agent calls in a single response:

# Research task — spawns 3 agents simultaneously
Agent({ description: "Auth patterns", prompt: "How does auth work in src/auth/?" })
Agent({ description: "DB schema", prompt: "What tables exist? Read prisma/schema.prisma" })
Agent({ description: "API routes", prompt: "List all API endpoints in src/pages/api/" })

Claude Code runs all three simultaneously. You get three reports back instead of three sequential explorations that eat your context window.

The Briefing Problem

Most subagent failures come from under-specified prompts. The subagent doesn't know:

• What you've already found
• Why this task matters
• What format you need the result in

This prompt fails:

"Check the database layer for issues."

This prompt works:

"I'm debugging a race condition in the checkout flow. Read src/db/orders.ts and src/db/transactions.ts. I need to know if there's any place a transaction could be committed without its dependent order record. Report specific line numbers. Under 200 words."

The second prompt includes: what you know, what you need, and a format constraint. All three are required for reliable subagent output.

Context Doesn't Transfer

The most common mistake: assuming the subagent inherits your session's context.

It does not. Every subagent starts fresh. If you've spent 20 turns establishing that "the users table is in the legacy schema," the subagent doesn't know that. You have to include it in the prompt.

Rule of thumb: write subagent prompts as if briefing a smart colleague who just walked into the room.

Subagent Types

For specialized tasks, you can specify a subagent type:

Agent({
  subagent_type: "oh-my-claudecode:code-reviewer",
  description: "Security review",
  prompt: "Review src/api/payments.ts for OWASP Top 10 vulnerabilities."
})

Available specialized types (if you have oh-my-claudecode installed):

• code-reviewer — security, logic, SOLID principles
• debugger — root cause analysis, stack traces
• architect — strategic architecture, read-only
• test-engineer — test strategy, coverage gaps

When Not to Use Subagents

Skip subagents when:

• The task is a single file read or grep — just use the tool directly
• You need the result to inform your next step before it completes — subagents are async, don't chain them if you need sequential results
• The task requires state that only exists in your main session

Use subagents when:

• You need to explore 3+ independent paths simultaneously
• A subtask will generate >5K tokens of tool output you don't need in main context
• You want a second opinion from a specialized agent without polluting your session

Real Usage Pattern

Here's how I use subagents when doing architecture work on an unfamiliar codebase:

1. First message: spawn 3-5 exploration agents in parallel to map the codebase
2. Second message: synthesize their reports in my main context
3. Implementation: work in main context with a complete picture

This compresses a 2-hour codebase exploration into 10 minutes. The subagents do the reading; I do the thinking.

---

All tools → whoffagents.com