What Are Subagents?
Subagents in One Sentence
A subagent is a specialized assistant that Claude Code can delegate a task to. It runs in its own separate conversation context, does its work — reading files, running searches, calling tools — and returns only a concise summary to your main thread. All the intermediate steps stay isolated and never clutter your main conversation.
The core idea
Think of a subagent as a focused helper you hand a self-contained task. It goes away, does the messy work in its own context window, and comes back with just the answer. You get the result without the noise of the journey it took to find it.
This matters because every message in Claude Code adds to your main context window — every tool call, file read, and search result is stored there. That space is finite. Once it fills up, Claude starts losing track of earlier parts of the conversation. Subagents are the primary tool for keeping long sessions focused and effective.
What a Subagent Receives — and Returns
When Claude Code spins up a subagent, the subagent gets exactly two inputs: a custom system prompt (defining its role and behavior) and a task description written by the parent agent based on what you asked. It then works independently. When it finishes, only its final summary returns to the main thread — and the entire subagent conversation is discarded.
The parent sends a task + system prompt; the subagent does all the messy work in isolation; only a clean summary comes back.
The tradeoff
You gain a clean main context, but you lose visibility into HOW the subagent reached its conclusion. That tradeoff is the whole game: it's worth it when you only need the result, and a poor fit when you need to watch and react to every step (more on that later).
A Concrete Example
Say you're exploring an unfamiliar codebase and ask: 'Which service handles refunds?' Without a subagent, Claude might read 15 files, run several searches, and trace through multiple function calls — and all of that fills your main context window, even though you only needed one fact.
With a subagent, the experience is clean. You ask the question, the Explore subagent spins up, does all that digging in its own context, and hands back a focused answer. Your main context window records only the question and the summary — not the 15 files read along the way.
| Without a subagent | With a subagent | |
|---|---|---|
| Files read land in main context | All 15 | 0 |
| Main context records | Question + 15 files + searches | Question + summary |
| You get | The answer, buried in noise | The answer, cleanly |
| Context budget consumed | Large | Tiny |
Same answer, vastly different cost to your main context window.
Built-in vs. Custom
Claude Code ships with built-in subagents you can use immediately, and lets you define your own. We'll cover both in depth, but here's the lay of the land:
- •Built-in: general-purpose (multi-step explore + act), Explore (fast read-only codebase search), and Plan (research during plan mode). More on each in a later lesson.
- •Custom: your own subagents with tailored system prompts and tool access — a code reviewer, a test writer, a documentation generator, anything your workflow needs.
Three benefits to remember
Subagents (1) break work into focused pieces so each one concentrates on a specific task, (2) keep your main context clean by isolating intermediate work, and (3) return just the information you need as a concise summary. The less noise in your main context, the longer and more effectively you can work.
Next
You know WHAT a subagent is. Next we'll dig into WHY context isolation is the feature that makes long Claude Code sessions possible at all.
Key Takeaways
- ✓A subagent is a specialized assistant Claude Code delegates a task to; it runs in its own context window and returns only a summary.
- ✓All intermediate work (file reads, searches, tool calls) stays isolated in the subagent and is discarded — keeping the main context clean.
- ✓A subagent receives exactly two inputs: a custom system prompt and a task description written by the parent.
- ✓The tradeoff: you gain a clean main context but lose visibility into how the subagent reached its conclusion.
- ✓Example: answering 'which service handles refunds?' can read 15 files in the subagent while your main context only records the question + answer.
- ✓Claude Code offers built-in subagents (general-purpose, Explore, Plan) and lets you create custom ones; the three core benefits are focus, clean context, and concise summaries.
Check Your Understanding
Test what you learned in this lesson.
Q1.What returns to the main conversation when a subagent finishes its work?
Q2.What two inputs does a subagent receive when it spins up?
Q3.Why do subagents matter for long Claude Code sessions?
Q4.What is the key tradeoff of using a subagent?
Practice This Lesson