Claude CodeLesson 13 of 25

Understanding Sub-Agents

As tasks grow larger, doing everything in a single conversation becomes a problem — context fills up, details get compressed, and quality drops. Sub-agents are Claude Code's answer: a main agent manages the work while specialist agents handle each piece in their own separate context window.

🧠

What is a sub-agent?

A sub-agent is a separate Claude instance that Claude Code spawns to handle a specific task. It has its own context window, works independently, and returns only a short summary back to the main agent. The main agent stays lean — it never sees the sub-agent's full working context.

✦ Own context window✦ Works independently✦ Returns summaries only✦ Spawned automatically

The Architecture

Let the main agent manage — let sub-agents do the work. Each sub-agent is a specialist. The main agent only receives a short summary when the sub-agent finishes.

How tasks flow through agentsOrchestration pattern
M

Main Agent

Manages the task

Plans workDelegates tasksReads summaries
dispatch
dispatch
dispatch
🔍

Explorer

Read-only search

Finds files, reads code, maps the codebase

✍️

Coder

Write & edit

Creates files, makes changes, runs commands

🔎

Reviewer

Quality check

Reviews code, flags issues, never edits

summary
summary
summary
Only short summaries return to Main — not the full working context
The main agent never sees all the intermediate code edits and file reads a sub-agent made — it only sees the final outcome. This is what keeps the main context clean.

Why Sub-Agents Matter — The Context Problem

Every Claude conversation has a context window. When it fills up, Claude compresses (compacts) older content. Important details get lost, earlier decisions are forgotten, and quality drops — even if you haven't noticed it happening.

✕ Single conversation

All work in one place

📈Context grows with every file read and edit
⚠️At 80% Claude compresses — older details lost
📉Quality degrades silently over the session
Context overloaded — quality drops

✓ Delegated to sub-agents

Heavy lifting happens elsewhere

📦Each sub-agent works in its own context window
📄Only a short summary returns to main
🎯Main stays under 20% — no compaction, no lost details
Main protected — quality stays high

Context usage comparison — same task

Without sub-agents — Main conversation80%

At 80% context compaction kicks in — older details are compressed and may be lost

With sub-agents — Main conversation15%

Main only receives summaries. Sub-agent used its own window for the heavy lifting

With sub-agents — Sub-agent context70%

Sub-agent can work freely in its own window — main conversation is unaffected

Common Sub-Agent Types

Claude Code ships with built-in sub-agents for the most common tasks. You can also define custom sub-agents for your project's specific needs.

🔍
Explorer AgentRead-only codebase navigator

Searches through files, reads code, and answers questions about the codebase. Never writes or edits files — purely a researcher.

> Find all API routes that use the Stripe client
✍️
Coder AgentFile writer and editor

Creates new files, edits existing ones, runs terminal commands, and implements features. The workhorse of the sub-agent system.

> Implement the POST /api/checkout endpoint
🔎
Reviewer AgentQuality and correctness checker

Reviews code for bugs, security issues, and adherence to conventions. Returns a structured feedback summary — never edits code directly.

> Review the new auth middleware for security issues
🧪
Tester AgentTest writer and runner

Writes unit and integration tests, runs the test suite, and reports failures. Handles all testing work without cluttering the main conversation.

> Write and run tests for the new formatCurrency utility

A Simple Worked Example

Task: "Add email notifications when a new user signs up." Here is how the main agent orchestrates sub-agents to complete it.

1
Main Agent

Receives the task. Plans: explore existing auth code → code the mailer → test it → review.

↳ Task plan created
2
Explorer Agent

Reads src/app/api/auth/, finds the signup route at src/app/api/auth/register/route.ts. Reads the existing user creation logic.

↳ Summary → signup happens in register/route.ts at line 34
3
Coder Agent

Creates src/lib/mailer.ts with sendWelcomeEmail(). Edits register/route.ts to call it after user creation. Installs nodemailer.

↳ Summary → mailer.ts created, route updated, nodemailer added
4
Tester Agent

Writes src/__tests__/mailer.test.ts. Runs npm run test. All 3 tests pass.

↳ Summary → 3 tests written, all passing
5
Reviewer Agent

Reviews mailer.ts and the route changes. Flags that the email address should be validated before calling sendWelcomeEmail.

↳ Summary → 1 suggestion: validate email before sending
6
Main Agent

Reads all four summaries. Asks the Coder Agent to add the email validation suggested by the reviewer.

↳ Done — email validation added. Task complete.
The main agent's context only grew by the size of the four short summaries — not by thousands of tokens of file reads and diffs that the sub-agents generated internally.

How Claude Invokes Sub-Agents

In most cases Claude Code handles sub-agent dispatch automatically when a task is complex enough. You can also invoke them explicitly in your prompt.

Automatic — Claude decides

For larger tasks Claude Code automatically plans and delegates to the right sub-agents. You just describe the outcome.

> Add email notifications when a user signs up. Write tests and make sure nothing in the auth flow breaks.

Explicit — you name the agent

You can call a specific sub-agent type by name to make intent clear, especially useful for review-only or explore-only tasks.

> Use an Explorer agent to find all places we call Stripe. Return a list of file paths only.
> Use a Reviewer agent to check src/lib/mailer.ts for security issues. Do not make any edits.
One key rule: always tell a reviewer or explorer agent not to make edits. Without that constraint, sub-agents may try to fix issues they find rather than just reporting them.

Sub-Agents — Quick Reference

🧠

Main agent = manager

Plans, delegates, collects summaries. Stays lean.

🔧

Sub-agent = specialist

Does one job. Returns a short summary to main when done.

📦

Each agent has its own context

Sub-agent context never flows into main. Main stays clean.

⚡

Sub-agents can run in parallel

Multiple sub-agents can work simultaneously on independent tasks.

🎯

Be explicit for review tasks

Tell reviewer/explorer agents 'do not edit' to avoid unintended changes.

📊

Quality stays high

Main at 15% context → no compaction → no lost details.

What's Next

Sub-agents covered. The next lesson walks through building one from scratch — role definition, instructions, and allowed tools.