Claude Code Subagents: Why the Best Coding Agents Delegate

What Subagents Are

A Claude Code subagent is a child agent spawned by the parent to handle a specific task. The parent gives the subagent a prompt, the subagent executes autonomously in its own context window, and returns a compressed result. The parent never sees the subagent's intermediate steps, failed searches, or dead ends. It gets the final answer.

This is the Agent tool in Claude Code. It works like any other tool (Read, Edit, Bash) except instead of reading a file or running a command, it spawns an entire Claude Code instance to do a job.

Unlike Agent Teams, subagents are not persistent collaborators. They do not talk to each other. They do not share a task list. They fire, execute, return, and disappear. The parent is the only coordinator. This makes subagents lightweight, cheap, and appropriate for the vast majority of multi-step coding tasks.

Why Delegation Matters

A single agent doing everything sequentially accumulates context. Every file it reads, every search result it scans, every test output it checks goes into the same context window. By token 80,000, the agent is wading through pages of irrelevant information to find the three lines it needs.

This is not a theoretical problem. Cognition published telemetry from Windsurf and Devin showing that search and navigation consume 60% of total agent time. The agent is fast at writing code. It is slow at finding where to write it.

Context Rot

As a context window fills, model attention degrades. Information in the middle of a long context gets less weight than information at the beginning or end. Research on long-context LLMs confirms this "lost in the middle" effect. An agent that has been running for 20 minutes has a context window full of old search results, superseded plans, and resolved errors. The information it needs right now competes with everything it has seen before.

Subagents solve this by giving each task a clean context. The search subagent starts fresh, finds what it needs, and returns a tight summary. The parent's context stays focused on the actual problem.

Parallel Execution

Sequential work has an obvious ceiling: the agent can only do one thing at a time. If finding the right file takes 30 seconds and running tests takes 45 seconds, a sequential agent spends 75 seconds before it can act on both results.

With subagents, both tasks run concurrently. The parent spawns a search subagent and a test subagent at the same time. Both return results, and the parent makes decisions with complete information in roughly 45 seconds instead of 75.

How Subagents Work

The lifecycle is straightforward:

1. Parent decides to delegate. Claude Code recognizes a task that benefits from isolation or parallelism. It calls the Agent tool with a prompt describing the job.
2. Subagent spawns. A new Claude Code instance starts with its own context window. It loads the project's CLAUDE.md, configured MCP servers, and any relevant skills. It does not inherit the parent's conversation history.
3. Subagent executes. It works autonomously, using whatever tools its type permits (Bash, Read, Edit, Grep, MCP servers). It can make multiple tool calls, read multiple files, and reason through the problem independently.
4. Result returns. When the subagent finishes, its output is compressed and returned to the parent as the Agent tool's result. The parent receives a summary, not the full transcript.
5. Subagent disappears. The child's context window is discarded. No state persists between subagent invocations.

# Parent's perspective:
# 1. Decides to search the codebase
# 2. Calls Agent tool: "Find all files that import the AuthProvider component"
# 3. Receives: "Found 12 files importing AuthProvider: src/app/layout.tsx,
#    src/components/dashboard/sidebar.tsx, src/middleware.ts, ..."
# 4. Continues working with that information

# Subagent's perspective (parent never sees this):
# 1. Spawns with clean context
# 2. Runs Grep for "import.*AuthProvider" across the codebase
# 3. Finds 47 matches, filters to actual imports (not re-exports)
# 4. Reads file headers to confirm usage patterns
# 5. Compresses findings into a structured summary
# 6. Returns summary to parent and terminates

The compression step is key. A subagent might read 30 files and run 15 grep queries during its execution. The parent receives a paragraph of results. This asymmetry keeps the parent's context clean and focused.

Subagent Types

Claude Code ships three subagent types. The right type depends on what the job requires.

General-Purpose Subagents

Full Claude Code instances with access to every tool the parent has. They can edit files, run terminal commands, call MCP servers, and make arbitrary changes to the codebase. Use these when the subagent needs to do real work, not just look around.

Common uses: running a test suite and reporting failures, creating a new file based on a pattern found elsewhere, applying a refactor across multiple files, installing a dependency and verifying it works.

Explore Subagents

Optimized for speed. Explore subagents use a smaller, faster model (Haiku-class) and only have access to read-only tools: Grep, Glob, and Read. They cannot edit files or run commands. This makes them fast and cheap for the most common subagent task: finding things in a codebase.

Claude Code spawns Explore subagents frequently and often without being asked. When the parent needs to understand how a module works, find where a function is called, or locate a configuration file, it typically delegates to Explore automatically.

Plan Subagents

Designed for thinking, not doing. Plan subagents analyze code architecture, map dependencies, and reason about design decisions. They have read-only file access but no terminal or edit capabilities. The output is analysis and recommendations, not code changes.

Plan subagents are useful when the parent needs to understand the shape of a problem before committing to a solution. "How is authentication structured in this project?" and "What would break if we changed this interface?" are Plan subagent territory.

Subagents vs Agent Teams

Both subagents and Agent Teams parallelize work. The distinction is whether workers need to communicate with each other.

Use subagents for most things. Search the codebase, run tests, explore a module, apply a pattern across files. The parent delegates, the subagent delivers, done.

Use Agent Teams when the problem requires genuine collaboration between workers. Code review from multiple angles where the security reviewer needs to respond to the performance reviewer's findings. Feature development where the frontend developer needs to know what API the backend developer is building. These are coordination problems, and coordination requires workers that talk to each other.

A useful heuristic: if you can describe the subagent's job in one sentence and the result in one paragraph, use a subagent. If you need a shared document, a task board, or a discussion thread, use Agent Teams.

When to Use Subagents

When Not to Use Subagents

Subagents add overhead. Spawning a child agent, loading project context, and returning results takes time. For simple, single-step operations, doing the work directly in the parent is faster.

• Single file reads: If the parent needs to read one file, Read is faster than spawning an Explore subagent.
• Simple grep queries: A single Grep call is faster than delegating to a subagent.
• Quick edits: Editing one function in one file does not benefit from delegation.
• Context already available: If the parent already has the relevant information in context, there is no benefit to delegating.

The break-even point is roughly 3-4 tool calls. If a task requires fewer than 3 tool calls, do it directly. If it requires more, consider delegation.

Practical Examples

These prompts demonstrate real subagent usage patterns. Claude Code decides internally whether to delegate, but prompt structure influences the decision.

Codebase Search

# Single search
> Find all files that use the deprecated calculateTotal function
> and show me how each one calls it.

# Parallel search
> Search the codebase for three things:
> 1. All React components that accept a "user" prop
> 2. All API routes that require authentication
> 3. All database queries that don't use parameterized inputs

# Architecture exploration
> How does the notification system work? Trace the flow from
> when a notification is created to when it appears in the UI.

Testing

# Run tests while continuing work
> Run the full test suite and report any failures.
> While that runs, let's start implementing the new endpoint.

# Targeted test investigation
> Run the auth tests and tell me why testTokenRefresh is failing.
> Include the relevant test code and the actual vs expected output.

# Test coverage check
> Check which functions in src/lib/billing/ have no test coverage.

Multi-File Refactoring

# Pattern replacement
> Replace all instances of our old error handling pattern:
>   try { ... } catch (e) { console.error(e) }
> with the new pattern that uses our ErrorReporter class.
> Apply across the entire src/ directory.

# API migration
> We're migrating from the v1 API client to v2.
> Find all v1 client usages and update them to the v2 interface.
> The v2 client uses async/await instead of callbacks.

Investigation and Analysis

# Dependency analysis
> What would break if we removed the lodash dependency?
> Check every import and suggest native replacements.

# Security review
> Review the authentication module for security issues.
> Focus on token handling, session management, and input validation.

# Performance investigation
> Our API response times increased after the last deploy.
> Compare the current middleware chain with what we had in
> the previous commit. Identify what changed.

Performance Impact

Subagents affect three performance dimensions: speed, accuracy, and cost.

Speed

Parallel subagents reduce wall-clock time linearly for independent tasks. Three Explore subagents searching different parts of a codebase complete in roughly the time of one, not three. The bottleneck shifts from sequential execution to the slowest individual subagent.

Accuracy

Context isolation improves accuracy by keeping the parent focused. Research on long-context models shows attention degradation as context length increases. A parent with 20,000 tokens of focused context makes better decisions than a parent with 100,000 tokens of accumulated search debris. Anthropic's 90% improvement metric on complex multi-agent tasks comes primarily from this effect.

Cost

Subagents are not free. Each child consumes tokens in its own context. But the parent receives a compressed result, so the parent's context grows slowly. Explore subagents use Haiku-class models, making codebase search 5-10x cheaper per query than running the same search in an Opus-class parent context.

The net cost depends on usage. For tasks requiring extensive search (refactoring, investigation, test analysis), subagents typically cost less total than a single session that accumulates context. For simple, linear tasks, the overhead of spawning a subagent is pure waste.

Making Subagents Faster with MCP Servers

Each subagent's speed depends on the tools available to it. A subagent using built-in Grep on a 50,000-file codebase runs grep sequentially. An MCP server like WarpGrep gives each subagent access to indexed, parallel code search that returns results in under a second regardless of codebase size.

On SWE-bench Pro, Claude Code with WarpGrep as an MCP server scores 57.5%, up from 55.4% stock. The improvement comes from subagents resolving search queries faster, which means the parent gets results sooner and makes decisions with fresher context. Morph's fast-apply model further accelerates the edit step, running at 10,500 tok/s for applying code changes.

Frequently Asked Questions

What are Claude Code subagents?

Subagents are child Claude Code instances spawned by a parent agent to handle focused tasks. Each gets its own context window, runs independently, and returns a compressed result. The parent never sees intermediate work. Subagents are built into Claude Code, require no flags, and work on any plan.

What is the difference between subagents and Agent Teams?

Subagents are fire-and-forget workers within one session. They do a job and report back. They cannot talk to each other. Agent Teams are fully independent Claude Code instances that coordinate through a shared task list and direct messaging. Subagents need no setup. Teams need an experimental flag. Subagents cost less tokens. Teams enable genuine multi-agent collaboration. Use subagents for most things. Use Teams when workers need to communicate with each other.

What types of subagents does Claude Code have?

Three types. General-purpose: full tool access including Bash, Edit, and MCP servers, for any task. Explore: read-only Grep, Glob, and Read, optimized for fast codebase search using a Haiku-class model. Plan: read-only file access for architecture analysis and design review. Claude Code selects the type automatically based on the task.

How do I trigger Claude Code to use subagents?

Claude Code decides based on the task. Prompts involving multi-file search, test execution, codebase exploration, or large-scale refactoring naturally trigger subagent usage. You can be explicit: "Use a subagent to search for all usages of X" or "Spawn an agent to run the test suite."

Can Claude Code run multiple subagents in parallel?

Yes. Multiple subagents can execute concurrently. A common pattern is spawning several Explore subagents to search different parts of the codebase simultaneously, or running a test subagent while the parent continues writing code.

Do subagents cost extra tokens?

Subagents consume tokens in their own context windows, but the parent only receives a compressed summary. Explore subagents use a cheaper Haiku-class model. The net cost is often lower than a single session that accumulates all search results, test output, and exploration noise into one growing context window.

Can subagents use MCP servers?

General-purpose subagents inherit all MCP servers from the parent session. Explore and Plan subagents are restricted to read-only built-in tools. If the parent has WarpGrep, a database MCP server, or any other tool configured, general-purpose subagents can use them.

How do subagents improve coding agent performance?

Two mechanisms. Context isolation prevents the parent from drowning in irrelevant information, improving attention and decision quality. Parallel execution reduces wall-clock time for independent tasks. Anthropic measured 90% improvement on complex tasks with multi-agent orchestration. Cognition's data shows 60% of agent time goes to search. Subagents target that 60% directly.