Claude Code subagent spawning too many (2026)

The Problem

Claude Code spawns subagents for parallel work, but without controls, a single task can trigger 5-15 subagents. Each subagent costs ~5,000 tokens in base overhead (system prompt, tool definitions, CLAUDE.md loading) plus 15K-40K tokens in actual work. A 10-subagent incident burns 200K-450K tokens ($0.60-$1.35 on Sonnet 4.6, $3.00-$6.75 on Opus 4.6). This is often the most expensive single incident in a development day.

Quick Fix (2 Minutes)

Add to CLAUDE.md:

## Subagent Rules
- Maximum 3 subagents per task
- Never spawn a subagent to read a file (use Read tool directly)
- Never spawn a subagent for grep/search (use Grep tool directly)
- Each subagent must target exactly 1 file

Why This Happens

Claude Code spawns subagents when it perceives tasks as parallelizable. Three triggers cause excessive spawning:

  1. Broad task descriptions: “Update all route files” triggers one subagent per file. With 15 route files, that is 15 subagents.

  2. Implicit parallelism: “Add tests for the auth module” may spawn subagents for each function to test, even when sequential execution would be more efficient.

  3. Recursive delegation: Without explicit rules, subagents can spawn their own subagents, creating an exponential tree.

The cost math per subagent:

  • Base overhead: ~5,000 tokens (system prompt + tools + CLAUDE.md)
  • Average work: ~25,000 tokens (file reads + edits + verification)
  • Total per subagent: ~30,000 tokens
  • Cost on Sonnet: $0.09 per subagent
  • Cost on Opus: $0.45 per subagent

Ten unnecessary subagents: $0.90 Sonnet, $4.50 Opus.

The Full Fix

Step 1: Diagnose

Watch for these symptoms during a session:

# Symptom 1: Multiple "[subagent]" or "Task:" indicators appearing in output
# Symptom 2: /cost showing rapid token increase (50K+ in a single turn)
# Symptom 3: Same file being read multiple times (by different subagents)
# Check current costs
/cost
# If tokens jumped by 100K+ in one response, subagents are likely the cause

Step 2: Fix

CLAUDE.md subagent controls:

# CLAUDE.md
## Subagent Controls (MANDATORY)
### Hard Limits
- Maximum 3 subagents per task, ever
- No nested subagents (subagents must not spawn subagents)
- Each subagent targets exactly 1 file
### When NOT to Use Subagents
- Reading files (use Read tool)
- Searching code (use Grep tool)
- Running commands (use Bash tool)
- Tasks touching fewer than 3 files (do sequentially)
### When Subagents Are Appropriate
- Editing 3+ independent files simultaneously
- Running independent test suites in parallel
- Generating multiple unrelated code files
### Delegation Format
Before spawning, state:
1. Why parallel execution is needed (not just convenient)
2. Which specific file each subagent will target
3. Confirm: "3 or fewer subagents, no nesting"

Alternative: task decomposition without subagents:

# Instead of one task that spawns 10 subagents:
claude "Update all route files to use the new auth middleware"
# Decompose into sequential tasks:
claude "Update src/routes/users.ts to use the new auth middleware.
Then update src/routes/posts.ts with the same pattern.
Then update src/routes/comments.ts.
Do these sequentially, not in parallel."

Sequential execution costs more turns but fewer tokens because there is no subagent overhead and no duplicate file reads.

Step 3: Prevent

# CLAUDE.md
## Task Sizing
- If a task would require more than 3 subagents, decompose it into smaller tasks
- Each smaller task should be completable in one session with 0-2 subagents
- Prefer sequential execution over parallel for tasks that share file dependencies

Cost Recovery

If subagents have already been spawned:

# Interrupt with Escape key if subagents are still running
# Compact the session
/compact
# Restart with explicit constraints
"Complete the remaining changes sequentially. Do NOT use subagents."

Prevention Rules for CLAUDE.md

## Subagent Cost Prevention
- Max 3 subagents per task (HARD LIMIT)
- No nested subagents
- No subagents for: Read, Grep, Bash, Git operations
- Each subagent: 1 file target, max 10 tool calls
- Before spawning: state why parallelism is needed
- If task needs 4+ subagents: stop and decompose the task first
- Prefer sequential edits for files that share imports

Expected savings: preventing 2-3 excessive subagent incidents per week saves 400K-900K tokens, worth $5.28-$11.88/week on Sonnet or $26.40-$59.40/week on Opus. Monthly: $23-$52 Sonnet, $115-$257 Opus.

When Subagents Are Worth the Cost

Not all subagent spawning is wasteful. Understanding when subagents provide positive ROI helps write better rules.

Positive ROI Scenarios

Editing truly independent files. When 3 files share no imports and no logical dependencies, parallel editing via subagents saves time and reduces context accumulation in the parent.

# Good subagent use case:
# File 1: src/components/Header.tsx (standalone component)
# File 2: src/components/Footer.tsx (standalone component)
# File 3: src/components/Sidebar.tsx (standalone component)
# These share no imports -- parallel editing is efficient

Batch test generation. When writing tests for 3 independent modules, each subagent can focus on one module without needing context from the others.

Negative ROI Scenarios

Files with shared dependencies. When files import from each other or share a common dependency, subagents re-read the shared files, duplicating token cost.

# Bad subagent use case:
# File 1: src/routes/users.ts (imports userService, authMiddleware)
# File 2: src/services/user.ts (imports userRepository)
# File 3: src/repositories/user.ts (imports prisma client)
# These form a dependency chain -- sequential editing is more efficient
# because context from file 1 informs edits to file 2

Simple tasks. A task that takes 3 tool calls does not justify the 5,000-token overhead of a subagent spawn.

Subagent Behavior Differences by Model

Behavior Sonnet 4.6 Opus 4.6
Spontaneous spawning Moderate Higher
Spawn overhead cost $0.015 (5K x $3/MTok) $0.075 (5K x $15/MTok)
Spawns per complex task 2-4 3-6
Responsiveness to limits Good Good

Opus is 5x more expensive per subagent spawn, making subagent budget rules even more critical when using Opus. An uncontrolled Opus task with 6 subagents costs $0.45 in spawn overhead alone, before any useful work.

Emergency Subagent Kill

When subagents are spawning out of control during a session:

# Step 1: Press Escape immediately to interrupt
# Step 2: Clear the session
/compact
# Step 3: Restart with explicit no-subagent instruction
"Continue the task sequentially. Do NOT use any subagents.
Make all changes in the main thread, one file at a time."
# Step 4: If the task is too large for one thread
"This task is too large. Break it into 3 sub-tasks.
Tell me what the 3 sub-tasks are. I will run them as separate sessions."

This emergency protocol prevents further token waste and gives the developer control over task decomposition.

Monitoring Subagent Frequency

Track subagent spawning frequency as a leading indicator of cost problems. If subagent usage increases week-over-week without a corresponding increase in task complexity, the CLAUDE.md rules may need tightening or the task descriptions may be getting vaguer.

A healthy ratio for most projects is 0.5-1.5 subagents per task on average. Above 2.0 subagents per task indicates over-spawning. Below 0.3 suggests over-restriction that may slow down genuinely parallel workflows.

Which model? → Take the 5-question quiz in our Model Selector.

Estimate tokens → Calculate your usage with our Token Estimator.

Try it: Estimate your monthly spend with our Cost Calculator.

See Also