What Is a Subagent? Claude Code’s Specialized AI Agent System Explained

What Is a Subagent?

A subagent is a child AI agent launched by a main agent to perform a specific task in its own isolated context. The term is most closely associated with Anthropic’s Claude Code and Claude Agent SDK, where subagents let developers delegate work such as codebase exploration, code review, or planning without polluting the main conversation’s context window.

Think of a subagent like a specialist team reporting to a project manager. The manager (main agent) hands off a well-scoped task, the specialist does the research in its own workspace, and only a concise report comes back. The manager never sees every single file the specialist opened or every tool call it made — just the final summary. This design dramatically reduces context bloat and enables true parallel execution across many tasks at once.

How to Pronounce Subagent

How Subagents Work

Subagents run in a separate conversational context from the main agent, meaning they have their own message history, system prompt, and (optionally) their own model and tool set. The main agent launches a subagent by calling a dedicated tool: in Claude Code this is the Agent tool; in the Claude Agent SDK this is the Task API. The parent passes in a task description and any context the subagent needs to get started.

Execution flow

An important point to keep in mind: all intermediate tool calls and file reads performed by the subagent are invisible to the parent. The parent only receives the subagent’s final message. That’s the whole point — the subagent absorbs the “noise” of exploration so the parent can focus on higher-level reasoning.

Built-in subagent types in Claude Code

Claude Code ships with several purpose-built subagent types. Developers can also register their own by creating Markdown files under a project’s .claude/agents/ directory.

Subagent Usage and Examples

Invoking a subagent from Claude Code

When Claude Code decides a task warrants delegation, it issues a tool call that looks roughly like this internally:

# Spawning a subagent in Claude Code (internal representation)
Agent({
  description: "Ship-readiness audit for current branch",
  subagent_type: "general-purpose",
  prompt: "Audit what's left before this branch can ship. Check: "
          "uncommitted changes, commits ahead of main, whether tests "
          "exist, whether CI-relevant files changed. Report a punch "
          "list — done vs. missing — under 200 words."
})

Defining a custom subagent

To add a project-specific subagent, create a Markdown file such as .claude/agents/security-reviewer.md with YAML frontmatter describing its role, tools, and (optionally) model:

---
name: security-reviewer
description: Reviews code diffs from a security perspective
tools: Read, Grep, Glob
model: sonnet
---

You are a security-focused engineer. Review the given diff for:

- SQL injection, XSS, CSRF vectors
- Hardcoded secrets (API keys, tokens, credentials)
- Authentication and authorization gaps
- Known CVEs in new dependencies

Report findings as a prioritized (HIGH / MEDIUM / LOW) bullet list
with suggested fixes and minimal code examples.

Keep in mind that teams typically build up a library of these specialized subagents — a security reviewer, a migration safety auditor, a performance analyzer — and let the main agent pick the right one based on context. In practice, the strongest patterns are parallel search (spawn multiple subagents for independent queries) and independent verification (review written by a different agent from the one that wrote the code).

Advantages and Disadvantages of Subagents

Advantages

Disadvantages

Subagent vs Multi-Agent Systems

It’s important to note that “multi-agent system” is a broader term. Multi-agent systems can include peer-to-peer agents that negotiate or vote, whereas a subagent explicitly implies a parent/child command hierarchy with a clear request-response contract.

Common Misconceptions

Misconception 1: “Spawning subagents is always faster”

You should note that launching a single subagent and waiting for its reply can actually be slower than letting the parent do the work directly. The performance win comes from concurrency — dispatching several subagents in parallel.

Misconception 2: “Subagents are smarter than the parent”

Subagents typically use the same model family as the parent. What makes them effective isn’t raw intelligence; it’s focused system prompts and dedicated context. In practice, teams often assign a smaller model (e.g., Haiku) to subagents to cut costs.

Misconception 3: “The parent sees everything the subagent did”

Note that the parent receives only the subagent’s final message. Intermediate tool calls and file reads are lost. If the parent needs detail, the subagent must include it in the final report.

Real-World Use Cases

Large codebase exploration

On a monorepo with hundreds of thousands of lines, asking the parent agent to grep and read its way to an answer quickly exhausts context. Delegating to an Explore subagent returns just a curated list of relevant files, leaving the parent room to do actual work.

Independent verification

After the parent proposes a fix for a tricky bug, spawning a subagent with a fresh context and asking it to review the change produces genuinely independent feedback — the subagent hasn’t seen the parent’s reasoning or prior dead-ends.

Parallel documentation research

When comparing three libraries, dispatch three subagents in parallel — each researches one library — then let the parent assemble a comparison table. In practice this compresses minutes of sequential investigation into one concurrent round-trip.

Branch ship-readiness audits

A good “can we ship this?” audit touches git status, test results, CI config, and feature-flag wiring. A general-purpose subagent can check all of those in one shot and return a short punch list.

Frequently Asked Questions (FAQ)

Q1: Does a subagent use the same model as the parent?

By default, yes. But each subagent definition can specify its own model in frontmatter (for example, model: haiku) to delegate cheap work to a smaller model.

Q2: Can a subagent spawn another subagent?

That depends on the implementation. Claude Code restricts nested spawning for some agent types to prevent runaway recursion.

Q3: Can I inspect a subagent’s internal reasoning after the fact?

Session logs may retain subagent transcripts in some environments, but from the parent’s perspective you’ll typically see only the final returned message.

Q4: How does this relate to Agent Skills and MCP?

Keep in mind these are different layers. Agent Skills package reusable know-how (instructions and resources). MCP (Model Context Protocol) is a standard for connecting agents to external tools. Subagents are simply child agents running in their own contexts. All three can be combined.

Q5: When should I not use a subagent?

If the task fits comfortably in the parent’s context and doesn’t need specialization, spawning a subagent adds latency and token cost for no benefit. Editing a single file or sending a message is usually best done by the parent directly.

Conclusion

• A subagent is a child agent launched by a main agent to work in its own isolated context.
• Its primary value is context efficiency and parallel execution, not raw intelligence.
• Claude Code ships with built-in types like general-purpose, Explore, and Plan.
• Custom subagents are defined as Markdown files under .claude/agents/.
• The parent receives only the subagent’s final message — plan the contract carefully.
• Assigning smaller models (Haiku) to subagents is a common cost-optimization.
• Avoid subagents for trivial tasks. Use them when parallelism or specialization really pays off.

References