Claude Code Subagents: How They Work in Practice

Most people discover subagents when they hit a specific problem: a task that generates a huge amount of output, or a task where the work would contaminate the main conversation context. Subagents are Claude Code's answer to that problem. Here's what they actually are, how they differ from other agent patterns, and the practical details that matter.

The problem subagents solve

When you give Claude Code a complex task, everything it does — tool calls, results, intermediate work — lives in the same context window. For most tasks, this is fine. The context stays manageable, and having the full history helps Claude Code reason about what it's done.

But some tasks generate so much intermediate output that they crowd out useful context. Running a full test suite, searching a large codebase, processing many files — the results fill the context window with data that Claude Code doesn't need to keep reasoning about. The main conversation gets noisy, and you may hit context limits on long sessions.

Other tasks need different tool access than the main session should have. A task that requires searching the web shouldn't need write access to the file system. A code review task that only reads files shouldn't have shell execution enabled.

Subagents handle both problems: they run in their own context window, with their own tool configuration, and only pass their final result back to the parent. The noise stays in the subagent's context. The main conversation stays clean.

What subagents actually are

A subagent is a Claude Code session launched by another Claude Code session to handle a specific task. The parent agent defines the task, the subagent executes it, and the parent agent receives the result.

In Claude Code, subagents are created using the Agent tool. The parent calls the Agent tool with a task description and optional configuration. Claude Code launches a new session (or process), runs the task, and returns the result as a tool output.

The subagent has its own context window, its own tool set, and its own execution environment. It doesn't inherit the parent's context — it only gets what the parent explicitly passes to it in the task description.

How they differ from the Agent tool

The Agent tool and custom subagents (defined in .claude/agents/) are related but different:

The Agent tool (invocable by Claude Code at runtime) is the mechanism. It launches a new Claude Code process, runs it with the given prompt, and returns the output. Any Claude Code session can use the Agent tool.

Custom subagent definitions (.claude/agents/*.md files) are specializations. They pre-define the system prompt, tool access, and model for a specific type of task. When Claude Code decides to use a subagent for a particular task, it can match to a custom definition if one fits.

You can use the Agent tool without any custom definitions — Claude Code will launch a generic session. Custom definitions let you configure specialized subagents for tasks you run frequently, ensuring consistent system prompts and appropriate tool access every time.

Writing a useful subagent definition

A custom subagent definition is a markdown file in .claude/agents/. It specifies:

---
name: code-reviewer
description: Reviews code changes for quality, security, and style issues. Use when asked to review a diff, PR, or set of file changes.
tools: Read, Glob, Grep
model: claude-haiku-4-5
---

You are a code reviewer. Your job is to read code changes and identify:
- Logic errors or bugs
- Security vulnerabilities
- Style inconsistencies
- Missing error handling
- Test coverage gaps

Return a structured report with findings organized by severity (high/medium/low).
Do not make any changes to files. Read only.

The key design decisions:

description is how Claude Code decides whether to use this subagent. Write it to match the natural language descriptions of tasks you want routed to this subagent.

tools constrains what the subagent can do. A reviewer that only needs to read files shouldn't have Bash or Write access. Minimal tools = smaller blast radius if something goes wrong.

model lets you use a cheaper or faster model for tasks that don't require the full capability of Sonnet or Opus. Haiku for classification and summarization, Sonnet for complex reasoning.

Patterns that work in practice

Verbose research. Searching documentation, reading many files, exploring a codebase to answer a question — these generate a lot of intermediate output. Delegating to a research subagent keeps the main session clean and lets you run research in parallel with other work.

Parallel file processing. If you need to process 50 files independently, launching 50 subagents would be excessive, but launching 5 each handling 10 files is reasonable. Each subagent processes its batch and returns a summary.

Isolated code review. A review subagent with read-only tools reviews a diff and returns a structured report. The main session doesn't need to wade through all the files the reviewer read.

Format conversion. Converting many files from one format to another is a good subagent task — repetitive, bounded, doesn't require reasoning across the full codebase.

Security scanning. A subagent that reads files and checks for known vulnerability patterns, with no write access — the isolation from the main session ensures it can't accidentally make changes.

Gotchas and limits

Context is not shared. The subagent only knows what you pass to it. If the subagent needs context from the main session (earlier findings, environment details, project conventions), you need to explicitly include that in the task description. Assuming the subagent has context it doesn't have is a common failure mode.

Results come back as text. The subagent's output is returned to the parent as a text blob. If you want structured output (JSON, a specific format), say so explicitly in the task description. Otherwise you'll get prose that the parent has to interpret.

Errors in subagents don't automatically surface. If a subagent fails or produces malformed output, the parent may not realize it unless it checks. Build in result validation when subagent output feeds into subsequent work.

Cost multiplies. Each subagent is a separate Claude session. Running many subagents in parallel means multiple sessions consuming tokens simultaneously. For Claude Code on a subscription plan, this runs through your usage faster than a single session would.

Depth limits. Subagents can themselves launch subagents, but deep nesting gets hard to reason about and debug quickly. Two levels is usually the practical limit before you want a different architecture.

Subagents are a clean solution to a specific class of problem. When the problem is "this task would contaminate my main context" or "I need tool isolation," they're exactly the right tool. When the problem is something else, they add overhead without clear benefit.