Explainer
Claude Code Subagents, Explained
A Claude Code subagent is a separate agent that the main session spawns to handle a focused task in its own context window, then reports back a result. Subagents keep the main thread's context clean and let Claude fan work out in parallel. Here is how they work, how to define your own, and when they help.
01 / Definition
When Claude Code hits a chunk of work that is self-contained — exploring a large codebase, running a batch of independent checks, drafting one piece of a bigger change — it can delegate that work to a subagent instead of doing it inline. The subagent gets its own fresh context window, does the task, and returns a concise result to the main agent, which carries on. Because the subagent's full transcript never lands in the main conversation, the main thread stays focused and its context window does not fill up with intermediate noise.
There are two ways subagents show up. Claude Code can spawn ad-hoc subagents on the fly (for example, several at once to explore different parts of a repo in parallel). You can also define reusable subagents as Markdown files in a .claude/agents/ directory — each with a name, a description of when to use it, the tools it is allowed to use, and its own system prompt — so the main agent delegates the right kind of work to the right specialist. People use the terms "agents," "subagents," and "agent teams" for these more or less interchangeably.
02 / What it does
-
Isolated context windows
Each subagent runs in its own context window. The main thread only receives the subagent's result, not its step-by-step work, so the primary conversation stays lean and on-task even across long sessions.
-
A custom role and tools per subagent
A reusable subagent is a Markdown file in .claude/agents/ with a name, a "use this when…" description, an allowed-tools list, and its own system prompt. That lets you build specialists — a reviewer, a test-writer, an explorer — each scoped to the right tools.
-
Parallel fan-out
Independent subtasks can run as several subagents at once — for example, reading multiple files or checking multiple candidates in parallel — which is faster than working through them one by one in the main thread.
-
When not to use them
Subagents add overhead. For a single-file read or a short sequential task, doing it directly in the main thread is faster and cheaper. Reserve subagents for parallel or genuinely independent workstreams.
03 / How it works
The main agent acts as an orchestrator: when it decides a task is a good fit for delegation, it spawns one or more subagents, each with its own prompt, allowed tools and fresh context window. Each subagent works to completion and hands back a summary — not its entire transcript — and the orchestrator uses those results to continue. Reusable subagents defined in .claude/agents/ let you control which specialist handles which kind of work; ad-hoc subagents cover one-off parallel exploration. The same idea is available programmatically through the Claude Agent SDK, which exposes subagents as part of its options.
The main thread holds the conversation and the plan; subagents are disposable workers with fresh context that go do one focused job and report back. Delegate to keep the main context clean.
04 / Who it's for
- Developers working in large codebases where exploration would otherwise flood the main context window.
- Anyone with independent, parallelizable subtasks — multiple files to read, multiple checks to run, multiple options to evaluate.
- Teams who want repeatable specialists (reviewer, test-writer, migrator) defined once in .claude/agents/ and reused across sessions.
- Less useful for short, single-step tasks where the delegation overhead is not worth it.
05 / Getting started
You do not have to configure anything to benefit — Claude Code spawns subagents on its own when a task fits. To build reusable ones, add Markdown files under .claude/agents/ with a name, description, tools and system prompt. The tutorial and install guide cover the basics; to do the same from code, see the Claude Agent SDK.
Our AI agents
From the team behind AI Coding Hub — agents that pick up where the code ends:
- AI document agentDraftlizeTurn rough notes, specs and transcripts into clean, structured docs with an AI doc agent.Try Draftlize →
- AI presentation agentDecklizeGenerate editable slide decks from a prompt or an existing doc with an AI presentation agent.Try Decklize →
- AI data agentTablizeQuery, clean and chart spreadsheets and CSVs in plain English with an AI data agent.Try Tablize →
FAQ
- What is a Claude Code subagent?
- A separate agent that the main Claude Code session spawns to handle a focused subtask in its own context window. It does the work and returns a concise result, keeping the main conversation clean.
- How do I create a subagent in Claude Code?
- Define it as a Markdown file in a .claude/agents/ directory with a name, a description of when to use it, an allowed-tools list, and a system prompt. The main agent then delegates matching work to it. Claude Code also spawns ad-hoc subagents automatically when a task fits.
- When should I use subagents instead of doing it directly?
- Use them for parallel or independent workstreams and for exploring large codebases without filling the main context. For a single-file read or a short sequential task, work directly in the main thread — subagents add overhead that is not worth it there.
- Do subagents share context with the main agent?
- No. Each subagent runs in its own isolated context window and only returns a result to the orchestrator — its full step-by-step transcript does not enter the main conversation. That isolation is the point: it keeps the main context lean.
- Are "agents" and "subagents" the same thing in Claude Code?
- In everyday use, yes — people say "agents," "subagents," and "agent teams" for the same feature: delegating work to additional Claude agents with their own context and tools. "Agent teams" usually implies several running together.