A single Claude Code session has one context window. Every file it reads, every search it runs, every tool result it gets back stays in that window until compaction clears it out. Subagents exist to break that constraint. A subagent is a delegated Claude instance that runs a task in its own isolated context and reports back a summary — not a transcript — to the agent that dispatched it.
If you have ever watched a main session burn thousands of tokens on an open-ended codebase search, then have nothing useful left in context for the actual fix, subagents are the fix. This guide covers what they are, how to define custom ones, and the patterns that actually work in production.
What a Subagent Actually Is
A subagent is invoked through the Agent tool (sometimes called Task in other harnesses) with a subagent_type parameter and a prompt describing the job. The subagent runs its own agent loop — its own tool calls, its own reasoning, its own context window — completely separate from the parent session. When it finishes, only its final output returns to the parent. Everything it read or tried along the way is discarded from the parent's perspective.
This is the entire value proposition: context isolation. A parent session that delegates a 50-file codebase search to a subagent pays for that search once, in the subagent's window, and receives back a three-paragraph summary instead of fifty files' worth of grep output.
Built-In vs. Custom Subagents
Claude Code ships with general-purpose subagent types out of the box — an Explore type tuned for open-ended codebase research is the most commonly used. You reach for it any time a search needs more than two or three rounds of grep/glob and would otherwise flood the parent's context with intermediate results.
Custom subagents go further: you define your own, with their own name, description, and restricted toolset, so the parent (or the harness itself) can pick the right specialist for the job automatically.
Defining a Custom Subagent
Custom subagents live as markdown files in .claude/agents/ — project-scoped in a repo, or ~/.claude/agents/ for ones you want available everywhere. Each file is a prompt with YAML frontmatter describing the agent's identity:
---
name: security-reviewer
description: Reviews code changes for OWASP Top 10 vulnerabilities. Use after any diff touching auth, input handling, or database queries.
tools: Read, Grep, Glob
model: sonnet
---
You are a security reviewer. For every file you are given, check for:
- SQL injection and command injection
- Missing input validation at trust boundaries
- Hardcoded secrets or credentials
- Broken auth/session handling
Report findings as a list with file:line references. Do not fix anything — only report.The description field is the single most important line in the file. It is what the parent session (or the harness's automatic delegation logic) reads to decide whether this subagent is the right one for a given task. Vague descriptions get skipped or misapplied. Write them the way you'd write a job posting: what triggers this agent, and what it's for.
The tools field restricts what the subagent can do. A review-only agent should not get Write or Edit — give it Read, Grep, and Glob, and it physically cannot make changes, no matter what the prompt inside a file it's reviewing tries to tell it to do. This is a real security boundary, not just tidiness.
Explicit vs. Automatic Dispatch
You can invoke a subagent two ways. Explicitly, by naming it directly in a request to the parent ("use the security-reviewer subagent on this diff"), or automatically, where the harness matches an incoming task against every registered subagent's description field and delegates on its own. Automatic dispatch is where the description field earns its keep — it is effectively the only signal the matching logic has.
Parallel Dispatch
Because subagents run in isolated context, independent ones can run concurrently. If you need to research three unrelated parts of a codebase, or run the same review agent against five separate pull requests, dispatch them together in one turn rather than sequentially. The parent session waits for all of them and gets back multiple independent summaries instead of one session serially re-reading five sets of files.
The failure mode to watch for is dispatching subagents that depend on each other's output in parallel — if agent B needs agent A's result, run A first, read its summary, then dispatch B. Parallelize only when the tasks are genuinely independent.
When to Use a Subagent vs. Just Doing It
Subagents have real overhead: spinning one up costs a round trip and the summary-compression step loses some fidelity versus having the raw data in front of you. Reach for one when:
- The search space is large and the useful signal is small. Fifty files searched, three lines that matter — perfect subagent case.
- The task is a genuine detour from the main thread. Researching a library's API while you're mid-refactor on something unrelated.
- You need the same specialized check run repeatedly. A security review, a style check, a test-coverage audit — define it once as a named subagent, invoke it every time the trigger condition matches.
- You want a hard tool boundary. A subagent with only Read and Grep cannot accidentally write to your filesystem, no matter what's in its prompt.
Skip the subagent when the task is simple, directed, and the result needs to live in your working context anyway — reading a single file you're about to edit, or a targeted grep for a known string. Delegating those just adds a round trip for no isolation benefit.
Subagents vs. Hooks vs. Skills
These three extension points solve different problems and are easy to conflate. A hook is a deterministic shell command that fires on a lifecycle event — it enforces a rule, it does not reason. A Skill is a bundle of instructions and resources the main agent loads into its own context to gain a capability, without spinning up a separate agent loop. A subagent is a separate reasoning agent with its own context window, dispatched for delegated work and reporting back a summary.
Rule of thumb: use a hook for hard constraints, a Skill for capability you want the main agent to have inline, and a subagent for work you want to keep out of the main context entirely.
Context Budgeting in Practice
The real-world payoff shows up on long sessions. A session that delegates all its exploratory research to subagents and keeps only decisions and diffs in its own context can run far longer before hitting compaction than one that does every search inline. If you are running agentic loops that need to survive for hours, subagent delegation for anything exploratory is close to mandatory — it is the difference between a loop that degrades as context fills up and one that stays sharp because its context stays small and decision-dense.
Common Mistakes
- Vague descriptions. A subagent description like "helps with code" will never get matched correctly by automatic dispatch. Be specific about the trigger condition.
- Giving a subagent every tool. If it only needs to read and report, restrict it to Read/Grep/Glob. Broad toolsets defeat the isolation boundary that makes subagents useful in the first place.
- Parallelizing dependent tasks. If task B needs task A's output, they are not independent — run them sequentially.
- Using a subagent for a two-second lookup. The dispatch overhead isn't worth it for anything you could answer with a single Read or Grep call.
The Bottom Line
Subagents are a context management tool disguised as a delegation feature. Every task you push into an isolated subagent context is context you keep out of your main session's window — which means more room for the decisions that actually need to live there. Start with the built-in Explore type for research tasks, then define one custom subagent for whatever specialized, repeatable check your workflow needs most (a security review, a style audit, a test-coverage pass), and let its description field do the routing.
Building Agent Infrastructure?
From subagent architecture to persistent memory to production deployment — our consulting team builds the agent systems behind long-running autonomous workflows. We ship code, not slide decks.