Claude Code: SubAgents
Last updated: 2026-08-31
Sub-agents turn Claude Code into a "team manager" — the main agent decomposes tasks, sub-agents execute in parallel, efficiency multiplies.
💡 Tip: Sub-agents aren't multiple Claude Code instances, but a parallel execution mechanism within a single session. The main agent plans and coordinates; sub-agents execute.
📋 Prerequisites: Chapter 12 - MCP
1. What You'll Learn
- How sub-agents work
- When to use sub-agents
- Parallel task execution
- Inter-agent collaboration patterns
- Scheduling and resource management
2. Sub-Agent Working Principles
(1) Architecture Model
graph TB
M[Main Agent<br/>Plan+Coordinate] --> S1[Sub-agent 1<br/>Frontend refactor]
M --> S2[Sub-agent 2<br/>Backend API]
M --> S3[Sub-agent 3<br/>Test writing]
S1 --> R[Result Aggregation]
S2 --> R
S3 --> R
(2) Execution Flow
TEXT
📖 Display only
1. User gives complex task
2. Main agent decomposes into independent sub-tasks
3. Creates sub-agent for each sub-task
4. Sub-agents execute in parallel (independent contexts)
5. Main agent aggregates all sub-agent results
6. Checks consistency, handles conflicts
7. Outputs final result
▶ Example 1: Sub-Agent Auto-Trigger
TEXT
📖 Display only
> Add complete user management module: data model, API, frontend, tests
Claude Code (Main Agent):
Task decomposition:
- Sub-task 1: Create data model (User model + migration)
- Sub-task 2: Create API endpoints (CRUD)
- Sub-task 3: Create frontend pages
- Sub-task 4: Write tests
[4 sub-agents launch in parallel]
Sub-agent 1: ✅ Data model created
Sub-agent 2: ✅ API endpoints created
Sub-agent 3: ✅ Frontend pages created
Sub-agent 4: ✅ Tests written
Main Agent: Aggregating, checking consistency...
→ Found API format mismatch with frontend expectations
→ Auto-correcting frontend API calls
→ Running full tests
✅ All 24 tests passed
3. When to Use Sub-Agents
| Scenario | Suitable? | Reason |
|---|---|---|
| Multi-file independent modifications | ✅ Yes | Files don't affect each other |
| Frontend+Backend parallel dev | ✅ Yes | Independent tech stacks |
| Batch test writing | ✅ Yes | Each test file independent |
| Single-file deep refactoring | ❌ No | No parallelism needed |
| Sequential dependent tasks | ❌ No | Can't parallelize |
| Small modifications | ❌ No | Overhead > benefit |
4. Parallel Task Execution
▶ Example 2: Parallel Bug Fixing
TEXT
📖 Display only
> Fix these bugs in parallel:
> 1. src/auth/jwt.ts: token refresh logic error
> 2. src/utils/date.ts: timezone handling issue
> 3. src/api/orders.ts: missing pagination validation
> 4. src/services/payment.ts: amount precision issue
Claude Code launches 4 sub-agents:
Sub-agent 1 [jwt.ts] → ✅ Fixed (2min)
Sub-agent 2 [date.ts] → ✅ Fixed (3min)
Sub-agent 3 [orders.ts] → ✅ Fixed (1min)
Sub-agent 4 [payment.ts] → ✅ Fixed (4min)
Total: 4min (serial would need 10min)
Savings: 60%
5. Inter-Agent Collaboration
| Mode | Description | Use Case |
|---|---|---|
| Fully independent | No interaction between sub-agents | Batch independent tasks |
| Shared conventions | Share CLAUDE.md and code style | Consistent team standards |
| Result integration | Main agent integrates sub-agent results | Consistency check needed |
| Iterative collaboration | One sub-agent's output feeds another | Dependencies exist |
6. Resource Considerations
| Dimension | Single Agent | 4 Sub-Agents |
|---|---|---|
| API calls | Serial | Parallel |
| Token consumption | 100K | 4 × 30K = 120K |
| Time | 10 min | 3 min |
| Cost | $2.00 | $2.40 |
❓ FAQ
Q Do sub-agents auto-trigger?
A Yes. Claude Code auto-detects when tasks can be parallelized. You can also explicitly request parallelism.
Q Is there a sub-agent limit?
A No hard limit, but each consumes independent context and API calls. Recommend max 5-6 parallel to avoid excessive resource consumption.
Q Can sub-agents communicate?
A Not directly. They coordinate through the main agent — which assigns tasks, aggregates results, handles conflicts.
Q Do parallel executions conflict?
A Possibly when modifying the same file. Main agent detects and resolves conflicts; recommend having parallel tasks work on different files.
Q Are sub-agents more expensive?
A Slightly (~10-20% more Tokens), but time savings are substantial (50-70%). Recommended for time-sensitive scenarios.
📖 Summary
- Sub-agents are Claude Code's internal parallel execution mechanism
- Main agent decomposes, sub-agents execute in parallel, main agent aggregates
- Best for multi-file independent modifications, batch operations, frontend+backend parallel dev
- Not for sequential tasks or simple modifications
- Parallel saves time but slightly increases cost; watch for conflicts
📝 Exercises
- Basic (⭐): Give Claude Code a parallelizable task, observe sub-agent auto-triggering.
- Intermediate (⭐⭐): Design a scenario with 4 independent modules, compare serial vs parallel time.
- Advanced (⭐⭐⭐): Analyze sub-agent Token consumption and cost, determine when parallel is worthwhile.
