Claude Code subagents: setup, use cases, and limits
Learn when Claude Code subagents help, how to create a read-only reviewer, and where a separate agent adds needless complexity.
A Claude Code subagent is a focused worker that handles one bounded task in a separate context, then returns the useful result to your main conversation. Use one for self-contained research, review, or verification. Keep the work inline when it is quick or needs constant back-and-forth.
This site is independent and is not affiliated with Anthropic. Product behavior in this guide was checked against Anthropic's documentation on July 11, 2026.
Pick the smallest tool that fits the job
Subagents are not the default answer to every complicated request. Start with the coordination the task actually needs.
| Use | When it fits | What happens |
|---|---|---|
| Main conversation | A quick change or a task needing frequent decisions | Claude works with the context already in the session |
| Skill | A repeatable procedure should run in the current context | Claude loads reusable instructions without creating a worker |
| Subagent | A bounded job has lots of disposable reading or output | A focused worker returns its result to the caller |
| Agent Team | Separate workers must message one another and coordinate shared work | Multiple Claude Code instances use a shared task list |
If Skills are the unfamiliar part, start with what Claude Skills are and how they work. A Skill packages a procedure. A subagent delegates a job to another context.
What a subagent receives
A normal subagent does not inherit the full conversation or every file already read by the main session. Claude prepares a delegation message, the subagent does its work in a separate context, and its result comes back to the caller. This is why a long review can avoid filling the main conversation with every search and file excerpt.
Fresh context does not mean a blank worker. Custom subagents normally load applicable project instructions, such as CLAUDE.md, plus a starting Git status snapshot. A forked subagent inherits the conversation so far. This example uses a normal, isolated subagent.
Before delegating, prepare a bounded context pack containing only the source files, rules, examples, and success test the worker needs.
Anthropic's subagent documentation lists three built-in types: Explore, Plan, and general-purpose. You can also define a custom one as a Markdown file with YAML frontmatter and instructions below it.
Build a read-only content reviewer
Suppose your publication has three finished MDX guides. You want a separate review pass for broken links, unsupported claims, and long paragraphs, but you do not want the reviewer editing the drafts.
Create this file inside the project:
.claude/agents/content-reviewer.md
Add the following definition:
---
name: content-reviewer
description: Reviews selected guide files against the supplied editorial checklist. Use when asked for an independent content QA pass.
tools: Read, Grep, Glob
model: inherit
maxTurns: 12
---
Review only the files named in the task. Apply only the supplied checklist.
Return a table with file, finding, evidence, and severity. Do not edit files.
Stop after the table and a five-line summary.
Project agents live in .claude/agents/, so the definition can be versioned and shared. Personal agents go in ~/.claude/agents/ and work across your projects.
tools: Read, Grep, Glob is what keeps this example read-only. Anthropic's permissions guide explains how deny, ask, and allow rules are evaluated.In Claude Code v2.1.198 and later, /agents no longer opens an interactive creation wizard. Ask Claude to create the file, or edit it directly. Existing agent directories are watched for changes. Restart Claude Code if you created the directory after starting the session and the agent does not appear.
Give it a precise assignment
Invoke the named agent in natural language or use its @ mention. Name the files, supply the checklist, and constrain the output:
Use @"content-reviewer (agent)" to review only these files:
- content/en/guides/claude-code-for-non-devs.mdx
- content/en/guides/claude-code-first-website.mdx
- content/en/guides/claude-code-pricing.mdx
Check for broken internal links, claims without primary sources,
paragraphs over 80 words, and banned marketing language.
Return only the evidence table and five-line summary.
Do not reopen the files in the main conversation.
The returned table should identify each file, locate the evidence, rate severity, and stop. You then decide what to fix. If the review is vague, improve the assignment before expanding the permanent instructions.
In Claude Code v2.1.198 and later, subagents run in the background by default. Claude runs one in the foreground when it needs the result before continuing. A background agent does not bypass safety checks: permission prompts still appear in the main session and identify which subagent is asking.
Do not treat separate context as proof that a review is unbiased or correct. Validate every finding against the file. It can reduce shared-conversation anchoring, but cannot guarantee independent judgment.
When delegation earns its overhead
Good subagent jobs have a clear finish line and produce a result you can merge once:
- reviewing a fixed set of files against a checklist;
- researching one documented product behavior;
- running a narrow test suite and summarizing failures;
- checking links, frontmatter, or accessibility issues;
- verifying one implementation after the main session finishes it.
Keep the task in the main conversation when it is tiny, needs rapid clarification, or shares substantial context with the next phase. A subagent must understand the assignment and gather its inputs. For a two-minute change, that startup work is needless latency.
The same warning applies to cost. A different model can be selected for a custom agent, but that does not guarantee lower token use or a lower bill. Model choice, context gathering, retries, and output length all matter. See Claude Code pricing before turning a repeated workflow into a large parallel run.
Honest limits
Intermediate work stays separate, but summaries return to the main session. Many verbose reviews can fill it anyway. A compact output contract matters as much as isolation.
There is also no current official universal concurrency number worth quoting. Product and session limits can change, so avoid plans that depend on running an arbitrary number at once.
Custom and general-purpose subagents can be resumed with their existing agent ID, retaining their earlier conversation and tool history. Built-in Explore and Plan agents are one-shot and cannot be resumed. Current documentation also allows nested subagents to a fixed depth of five below the main conversation. Nesting does not turn them into a peer team.
Permission inheritance has sharp edges too. A parent session using acceptEdits, auto, or bypassPermissions can take precedence over a subagent's requested mode. For safety-sensitive work, review the current permission modes rather than assuming a prompt can tighten the parent session.
Subagents are not Agent Teams
A subagent is a worker called from a session, and its result returns to the caller. Agent Teams are separate Claude Code instances that can communicate with one another and coordinate through a shared task list. That higher coordination model is experimental and disabled by default as of this source check.
Use a subagent when only the final result needs to come back. The Agent Teams vs subagents comparison is the next step when workers need to discuss dependencies, challenge one another, or update shared ownership while the work is happening. Anthropic's Agent Teams documentation is the primary reference for that experimental feature.
What is a subagent in Claude Code?
A subagent is a specialized worker that completes a delegated task in its own context and returns a result to the calling session. It is useful when the intermediate research, logs, or file reads are not needed in your main conversation.
How do I create a Claude Code subagent?
Create a Markdown file in .claude/agents/ for a project agent or ~/.claude/agents/ for a personal agent. Add YAML frontmatter with at least name and description, then write the worker's instructions below it.
When should I use a subagent instead of the main conversation?
Use one for bounded, self-contained work with a clear output, especially review, research, or verification. Stay in the main conversation for quick edits, latency-sensitive work, or tasks needing frequent clarification and shared context.
Can a Claude Code subagent edit files?
Yes, if its available tools and permission rules allow edits. For a review-only worker, enforce read-only behavior with an explicit allowlist such as Read, Grep, Glob. A sentence saying “do not edit” is an instruction, not an access control.
If subagents still sound like too much machinery, Claude Code for non-developers gives you the simpler foundation first. Create one agent only when you can describe its input, scope, allowed tools, output, and stopping condition in a few lines.