What Are Claude Code Subagents?
Claude Code subagents are independent Claude instances spawned by a parent agent during a session. The parent delegates a discrete task to the subagent, waits for the result, and then continues its own work. Each subagent runs with its own context window — completely isolated from the parent's conversation history and in-memory state.
Subagents are created via the Agent tool — a first-class Claude Code tool alongside Bash, Read, Write, and Edit. When Claude calls the Agent tool, it's essentially running a fresh Claude session with a specific goal, then returning that session's output as a string the parent can use.
A single Claude context window is finite. With subagents, you can decompose work into specialized roles — each with its own full context budget — and run them in parallel or sequence. A research subagent can crawl documentation while a code-review subagent audits your codebase, with neither crowding the other out of context.
The mental model is a team of contractors. The parent Claude is the project manager. It breaks work into chunks, delegates each chunk to a specialist, collects results, and assembles the final output. The specialists don't know about each other. They just complete their task and report back.
This architecture is especially powerful when tasks are:
- Long and context-hungry — each subagent gets a full context budget without competing with other work
- Parallelizable — the parent can spawn multiple subagents and aggregate their results
- Role-specific — a code reviewer needs different instructions than a documentation writer
- Repetitive — run the same auditor agent across 20 files without re-prompting each time
How the Agent Tool Works
The Agent tool is invoked like any other Claude Code tool — by Claude including a tool call in its response. You can also describe subagent behaviors in your CLAUDE.md to guide when and how Claude uses the Agent tool.
The tool accepts the following parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| description | string | yes | Short label for the task — Claude uses this to identify the subagent in its reasoning |
| prompt | string | yes | The full instruction sent to the subagent — its entire context. Be specific about expected output format |
| subagent_type | string | optional | Which subagent runs: a built-in one (general-purpose, Explore, Plan) or the name of a subagent you defined in .claude/agents/. That file supplies the subagent's system prompt, tools and model, so this is a selector, not a loose hint. A name with no matching file does not resolve (see the next section) |
Here's what an Agent tool call looks like in practice — this is what Claude emits when you've instructed it to use a research subagent:
The subagent's response comes back as a string in the parent's tool result. The parent can then parse it, pass it to another subagent, or use it directly. To wire this behavior, add agent instructions to your CLAUDE.md:
Subagents do NOT share the parent's context. Any information the subagent needs — files, prior decisions, constraints — must be explicitly included in the prompt parameter. If the parent read a file and made changes, the subagent won't know unless you pass that content in. See Common Mistakes for the full list of context-sharing pitfalls.
The Agent tool is available in Claude Code sessions by default — you don't need to install anything. It's part of Claude's built-in tool set, alongside Bash, Read, Write, Edit, Glob, and Grep. What you DO need is a clear instruction architecture in your CLAUDE.md so Claude knows when and how to use it.
How to Define a Custom Subagent (.claude/agents)
The Agent tool is how Claude delegates. What it delegates to is a subagent you write once as a Markdown file. In Anthropic's words, “Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.” Claude Code also ships built-in subagents (general-purpose, Explore and Plan) that it uses on its own.
When two subagents share a name, Claude Code uses the one from the higher-priority location:
| Where the file lives | Scope | Priority |
|---|---|---|
| Managed settings | Organization-wide | 1 (highest) |
--agents CLI flag | Current session | 2 |
.claude/agents/ | Current project | 3 |
~/.claude/agents/ | All your projects | 4 |
Plugin's agents/ directory | Where the plugin is enabled | 5 (lowest) |
Commit project subagents in .claude/agents/ to version control so your team gets the same reviewer. Keep personal ones in ~/.claude/agents/.
The file format
The file is YAML frontmatter followed by the subagent's system prompt. “Only name and description are required.” The description matters most, because “Claude uses each subagent's description to decide when to delegate tasks.”
Optional fields include tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort and isolation.
Field names are camelCase and must match exactly: “Claude Code ignores a field it doesn't recognize without reporting an error.” A file that says max_turns: 5 runs as if the line were not there, and nothing tells you.
Three ways to run it
On current versions, typing /agents just reminds you to edit those folders directly. On Claude Code v2.1.197 and earlier it opened an interactive wizard, which is what older tutorials show.
We put a one-line codeword in a test subagent file at .claude/agents/codeword-keeper.md. Running claude -p --agent codeword-keeper returned the codeword. A plain request (“Use the codeword-keeper subagent to get the codeword”) made Claude emit an Agent call with subagent_type set to codeword-keeper, and the codeword came back. Asking for a name with no file failed with --agent 'no-such-agent-zz' not found and a list of the agents that do exist.
Capping how deep subagents nest
Per Anthropic's docs, “By default, a subagent can spawn subagents of its own, up to three layers below the main conversation.” The limit is the CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH environment variable, and setting it to 1 turns nesting off. That is a hard limit, unlike an instruction in CLAUDE.md, which the model can misread.
Source for the quoted lines and the file-location table: Anthropic, Claude Code subagents documentation, read 16 Oct 2026. Field lists change between releases, so check it before you rely on a field.
5 Subagent Patterns That Work in Production
These are the patterns that consistently produce reliable results across real Claude Code deployments. Each card shows the subagent type, the trigger condition, and a minimal prompt configuration.
Research Agent
Delegates all deep research tasks — library comparisons, API documentation, best practices, competitive analysis. The parent stays focused on the task while the research agent does the reading.
Code Review Agent
Audits a specific file or function for bugs, security issues, performance problems, and style violations — without needing the parent to explain the entire codebase context.
Test Runner Agent
Generates, runs, and interprets tests for a given module. Can write missing tests, identify coverage gaps, and flag test cases that are testing the wrong thing.
Deploy Validation Agent
Checks all pre-deploy conditions before code ships: environment variables present, config files valid, dependencies installed, schema migrations applied, health endpoints reachable.
Documentation Agent
Generates comprehensive documentation for a module, API, or system — without requiring the parent to context-switch into writing mode. Pass it the source code, get back production-ready docs.
A powerful real-world pattern is the audit pipeline: spawn a code-review agent and a test-runner agent in sequence, feed the code-review output into the test-runner prompt (so it writes tests that specifically cover the flagged issues), then feed both outputs into a doc-writer agent. Three subagents, one cohesive workflow. Each runs with full context. Total parent context used: minimal.
Sequential vs. Parallel vs. Hierarchical Agents
The Agent tool supports all three topologies. The right choice depends on whether your tasks have dependencies, and whether you need specialization at multiple levels.
| Topology | How it works | Best for | Main tradeoff |
|---|---|---|---|
| Sequential | Parent spawns subagent A, waits, passes A's output to subagent B, waits, continues | Pipelines where step 2 depends on step 1 output. Audit → fix → verify. | Slower — each subagent blocks the next. Output errors cascade downstream. |
| Parallel | Parent spawns multiple subagents simultaneously (Claude batches Agent tool calls), collects all results, then continues | Independent tasks: research + code review + test generation running at once | Harder to orchestrate. Parent must merge conflicting outputs. Context cost multiplies. |
| Hierarchical | A subagent itself spawns further subagents (sub-subagents) to break its own task down | Very large codebases where a single "review" task needs to branch into per-file reviewers | Deep nesting becomes hard to debug. Cost and latency multiply at each level. Use sparingly. |
| Hybrid | Parallel spawn for independent tasks, sequential handoff for dependent tasks within each branch | Most production workflows. Research and review in parallel, then sequential fix → validate → document. | Requires careful orchestration logic in CLAUDE.md to keep parent from getting confused. |
For most teams starting with subagents, sequential patterns are recommended first. They're easier to debug, easier to audit in logs, and less prone to the output-merging complexity that parallel topologies introduce. Once you have sequential pipelines working reliably, add parallelism to the independent branches.
For orchestrating complex agent topologies, consider pairing subagents with Claude Code hooks — hooks can checkpoint state between subagent calls, log every agent's output to disk, and trigger notifications when a subagent fails.
Common Mistakes With Claude Subagents
Most subagent failures fall into five predictable categories. Understanding them before you build saves significant debugging time.
Assuming subagents share context with the parent
The single most common mistake. Subagents start with a completely blank context. They don't see the parent's conversation, the files the parent has read, or the in-memory changes the parent has made. If your parent Claude just edited auth.py, a subagent asked to "review auth.py" will read the original file from disk — not the parent's version.
Not specifying output format
A subagent that returns freeform prose is nearly useless to a parent agent that needs to parse and act on results. If you ask for a code review and get three paragraphs of narrative, the parent has to either pass that prose to yet another agent for parsing, or hallucinate a structured interpretation. Always specify the exact output format — preferably JSON with a schema — in the prompt.
Fix: End every subagent prompt with "Output ONLY: [format spec]" — no prose, no preambleSpawning too many subagents in sequence
It's tempting to decompose every step into a subagent. But each Agent tool call adds latency and consumes tokens at both the call and return points. A chain of 8 sequential subagents for a task that could be done in 3 compounds errors — a failure at step 5 means 4 wasted subagent runs. Design subagents to be substantial units of work, not thin wrappers around a single tool call.
Fix: Each subagent should do 5–10 minutes of human-equivalent work. If it's under 30 seconds, keep it in the parent.No error handling on subagent output
Subagents can return malformed JSON, empty responses, or error messages instead of results — especially when the task is ambiguous or the model hits a content boundary. Parents that blindly pass subagent output downstream cause cascading failures. Always validate before consuming: check that expected keys exist, values are non-empty, and format matches the spec.
Fix: Add explicit validation in CLAUDE.md — "If subagent output fails JSON.parse(), re-prompt once with a format correction instruction"Infinite delegation loops
A hierarchical agent setup where subagents themselves spawn subagents can create runaway delegation. If the orchestration logic isn't explicit about termination conditions, Claude can enter delegation chains that consume enormous amounts of context and tokens before completing any real work. Cap the depth with a setting, not only with a sentence the model has to follow.
Fix: Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (1 turns nesting off; the default allows three layers), and still state when a subagent should stop in its own prompt. How depth worksWhere Brainfile fits
Everything on this page is free to copy: the patterns, the mistakes and the depth limits. Brainfile does not sell pre-built subagents. It is the layer around them — the files that keep a Claude Code project organised from one session to the next, so whatever agents you write have a backlog to work from and a record of what was asked.
The Autopilot run protocol and 10 pattern files: a never-empty backlog, a ledger that tracks every ask until it is done, interview onboarding, an end-of-run brief, conversation history and a memory starter — plus a weekly freshness feed as Claude Code changes. Pro adds 15 role packs, a role-tuned CLAUDE.md per profession.
Try it free for 30 days.
No card, email only. The trial runs the Basic pull: the Autopilot protocol, the 10 pattern files and the weekly freshness feed. Every file you pull is yours to keep.
Paid plans: 30-day money-back guarantee · Cancel anytime