Sub-agents in Claude Code

Specialized agents running in isolated context windows

🤖 Sub-agents

Spawn specialized Claude Code agents that run in their own isolated context — enabling true parallelism and separation of concerns.

Official Docs →

1. What Are Sub-agents?

Sub-agents are separate Claude Code instances that are spawned by a parent agent to handle specific tasks. Each sub-agent runs in its own isolated context window, meaning it has no memory of the parent's conversation or other sub-agents' work.

🔀 Sub-agents enable parallel execution with clean isolation between tasks.

2. How Sub-agents Work

The parent agent uses the Agent tool to launch sub-agents:

1️⃣

Parent defines task

Parent agent specifies a prompt and optional tools for the sub-agent to use

2️⃣

Sub-agent executes

Runs in isolation with its own context, tools, and execution environment

3️⃣

Result returned

Sub-agent returns its output as a single message back to the parent

3. Key Benefits

✅

Parallel execution

Multiple sub-agents can run simultaneously, cutting total time

✅

Context isolation

Each agent has a fresh window — no cross-contamination of state

✅

Specialization

Give each sub-agent a focused prompt and only the tools it needs

✅

Large task decomposition

Break complex work into manageable parallel sub-tasks

4. Practical Example

A common use case is code review across multiple files simultaneously:

# Parent agent launches 3 sub-agents in parallel

Agent(description="Review auth module", prompt="Review auth/routes.py for security issues")
Agent(description="Review API module", prompt="Review api/endpoints.py for performance issues")
Agent(description="Review DB layer", prompt="Review db/models.py for query optimization")

All three run concurrently. The parent collects all three results and synthesizes a final report — much faster than sequential review.

5. Best Practices

→ Be explicit in prompts — sub-agents have no parent context; include everything they need to succeed.
→ Limit tool access — only pass the tools the sub-agent actually needs to reduce risk.
→ Verify results — always review sub-agent output before acting on it, as isolated agents can make different assumptions.
→ Use for independent work — sub-agents excel when tasks have no dependencies on each other.