- A subagent is a worker with its own context window. It does one task, returns a summary, and keeps the noise out of your main conversation. Its requests still count against the same usage limits.
- A custom subagent is one Markdown file. Put it in
.claude/agents/for a project or~/.claude/agents/for every project. Onlynameanddescriptionare required. - Tool limits in the file are enforced. A reviewer with
tools: Read, Grep, Globcannot edit, whatever the prompt says. - Delegation is not free. Each subagent rebuilds context from nothing, and you only see what it chooses to report.
- Our rule: delegate large, independent, parallel work. Do everything else in the main conversation, including checking your own work.
- What bit us: nine research agents hitting a usage limit together, a ten-agent run filling the disk, and two screens that passed alone and broke when combined.
Claude Code subagents are the first feature people reach for when a session feels slow, and the first one that makes a session expensive. Used well, they keep a long conversation clean. Used by reflex, they triple the bill and hand you back a confident summary of work you can't see.
We run Claude Code every day at Rough Works, and our global instruction file has a whole section on when not to delegate. This guide covers both halves: how subagents work as of November 2026, straight from the documentation, and the rules we wrote after getting it wrong. If you are new to the wider picture, start with AI agents explained and come back.
What Claude Code subagents are
A subagent is a second Claude that your session starts for one task. The subagents documentation describes it this way: each one "runs in its own context window with a custom system prompt, specific tool access, and independent permissions." It does the work, then returns a summary to the conversation that started it.
Three facts follow from that, and most confusion about subagents comes from missing one of them.
- It starts cold. A subagent does not see your conversation. It gets its own system prompt, basic environment details such as the working directory, and the task prompt Claude writes for it. Whatever you worked out over the last hour is not there unless it is in that brief. (The exception is a fork, which inherits the whole conversation. More on that below.)
- You see the summary, not the work. The file reads, searches and command output stay in the subagent's context. That is the benefit, and it is also the risk.
- It spends from the same pool. The docs are explicit that a subagent "sends its own requests, which count toward the same usage limits as your main conversation." Subagents save context. They do not save tokens.
Subagents also live inside a single session. Other ways to run work in parallel are compared near the end.
The built-in subagents you already use
You have probably been using subagents without defining any. Claude Code ships several, and Claude delegates to them on its own. As of November 2026 the documented set is:
| Built-in | What it does | Tools |
|---|---|---|
Explore |
Fast codebase search and analysis. Claude asks for a thoroughness level: quick, medium or very thorough | Read-only; Write and Edit are denied |
Plan |
Gathers context during plan mode before a plan is presented | Read-only |
general-purpose |
Multi-step tasks that need both exploration and changes | Every tool available to subagents |
claude |
Catch-all when nothing more specific fits | Every tool available to subagents |
statusline-setup, claude-code-guide |
Helpers for configuring the status line and answering questions about Claude Code | Narrow |
One detail matters for cost and for behaviour. Explore and Plan start without your CLAUDE.md files, to keep research fast. Other built-in and custom subagents load them, unless a custom definition sets omitClaudeMd: true. If you have rules in CLAUDE.md that a search agent appears to ignore, that is why.
A confession that is also a recommendation: we have no custom agent files on our own machine. Everything we delegate goes to the built-in types with a carefully written brief. A custom subagent earns its place when you keep spawning the same kind of worker with the same instructions. Until then, the brief is the thing to get right.
How to create a subagent in Claude Code
A custom subagent is a Markdown file with YAML frontmatter. Where you save it decides who gets it. When two definitions share a name, the higher row wins:
| Location | Scope |
|---|---|
| Managed settings | Whole organisation |
--agents CLI flag (JSON) |
Current session only |
.claude/agents/ |
Current project; commit it to share with the team |
~/.claude/agents/ |
All your projects |
A plugin's agents/ directory |
Wherever the plugin is enabled |
The steps:
- Decide the scope. Project agents belong in the repo so everyone gets the same reviewer. Personal ones go in your home directory.
- Write the file, or ask Claude to: "Create a read-only link-checker subagent in
~/.claude/agents/." Claude writes the frontmatter and the prompt. - Read what was written. Check the
toolsline in particular. Claude Code ignores a frontmatter field it does not recognise, without an error, and field names are camelCase (maxTurns,disallowedTools). - Try it: "Use the link-checker agent on the files I just changed."
- Restart only if it is not found. Claude Code watches both agents directories and picks up changes within a few seconds. The exception is a directory that did not exist when the session started.
Two things catch people who learned this earlier: /agents now prints a reminder pointing at those two directories, where older versions opened a wizard. And it is unrelated to claude agents, the shell command that opens the background-session view.
A complete agent definition file
Here is a full definition in today's documented format. It is an illustration written for this article, not a file we run in production.
---
name: link-checker
description: Checks that every URL in the given files resolves. Use before publishing copy, ads or config that reference URLs.
tools: Read, Grep, Glob, Bash
model: haiku
maxTurns: 30
---
You check links. You do not edit files.
For each file you are given:
1. Extract every URL and every root-relative path.
2. Request each one with `curl -sIL -o /dev/null -w "%{http_code}"`.
3. Treat 2xx and 3xx as passing. Anything else fails.
Report a table of failures only: file, line, URL, status code.
If everything passes, say so in one sentence. Do not suggest fixes.
Save it as ~/.claude/agents/link-checker.md. The filename does not have to match name; identity comes from the frontmatter.
What each part is doing:
nameis the identifier. It cannot contain a colon, which is reserved for plugin-scoped names such asmy-plugin:reviewer.descriptionis what Claude reads to decide when to delegate. It is loaded into every session, so keep it short. Claude Code warns at startup when the combined descriptions of your custom subagents pass 15,000 tokens.toolsis an allowlist. Leave it out and the subagent inherits every tool available to subagents, including your MCP servers.modelputs a simple job on a smaller model.maxTurnscaps the run. When the limit is reached, the output comes back marked as partial.- The body is the entire system prompt. A subagent does not receive the standard Claude Code system prompt, so anything it needs to know about how you work goes here or in CLAUDE.md.
Other documented fields: disallowedTools (a denylist), permissionMode, skills (preload full skill content), mcpServers, hooks, memory, background, effort, omitClaudeMd and isolation: worktree, which gives the subagent its own copy of the repository. Check the frontmatter reference before relying on any of them.
One caution about the example. Bash is on its tool list because it needs curl, and a shell can write files. An allowlist decides which tools exist, not what a tool is used for. If you want a subagent that truly cannot change anything, give it Read, Grep, Glob and nothing else.
Model selection and tool restrictions
Model. The model field takes an alias (sonnet, opus, haiku, and others your account offers), a full model ID, or inherit. When several things set a model, Claude Code takes the first of these:
- The
modelparameter Claude passes when it starts the subagent - The
modelfield in the definition - The
CLAUDE_CODE_SUBAGENT_MODELenvironment variable - The main conversation's model
So a subagent with no model line runs on whatever your session runs on. That is a sensible default and an expensive one if the job is counting imports. The best practices page is blunt about what you get: by default it is "the same model (or a smaller one) on the same task. You get parallelism or a fresh pair of eyes out of it, but not a smarter answer."
Tools. tools allows, disallowedTools denies, and if you set both, the denylist is applied first. Three behaviours that are not obvious:
- A
disallowedToolsentry with a specifier, such asBash(git push *), removes the whole Bash tool, not just that command. To block specific commands and keep the shell, add a deny rule topermissions.denyin settings. That rule applies to the main conversation and to subagents. - MCP servers are addressed by prefix.
mcp__github__*intoolsgrants one server's tools;mcp__*indisallowedToolswithholds all of them. - Background subagents get a smaller built-in tool set than foreground ones, and background is the default. The same definition can resolve to different tools depending on how it runs.
Subagents can also carry their own hooks. If you want a guard that applies only while one subagent runs, see our guide to Claude Code hooks.
How subagents get invoked
There are four routes, from least to most explicit:
- Automatic. Claude matches your request against each
description. Phrases such as "use proactively" in a description encourage it. - By name in plain language. "Have the code-reviewer subagent look at my recent changes." Claude usually delegates, but it decides.
- By @-mention. Type
@and pick the agent from the typeahead, or type@agent-<name>. This tells Claude to run that subagent for the task. - As the whole session.
claude --agent code-reviewerstarts a session where the main thread takes on that agent's prompt, tools and model. Setting"agent"in.claude/settings.jsonmakes it the project default.
By default, a subagent Claude starts from the main conversation runs in the background, and its result arrives as a notification in a later turn. When a background subagent needs permission for a tool call, the prompt appears in your main session with the subagent's name on it.
A fork is the variant that inherits your full conversation. You start one with /subtask, and Claude starts them itself while fork mode is on, which is the default. Forks skip the cold start and carry your whole context with them.
Two limits bound all this, both adjustable by environment variable. By default 20 subagents can run at once in a session, and subagents can nest up to three layers below the main conversation. The second number exists because a subagent can spawn its own subagents, such as a reviewer that dispatches one verifier per finding.
What delegation costs, and the rules we work by
The delegation section of our global CLAUDE.md opens with this sentence: "Subagents multiply cost and latency — each one re-establishes context, re-explores, reports back, and then you re-read the report." Four rules follow it.
- Delegate only large, independent, parallel work. A wide investigation across many files. Several unrelated tracks. Not something you could finish in a handful of tool calls.
- Do not use a subagent to check your own work. Verification belongs in the main conversation, where the evidence is. A reviewer that has not seen how the code was written is a different and legitimate thing; a second pass over an answer you just produced is not.
- If one subagent can do it, use one. Brief it precisely the first time. Launch, wait, re-brief is the expensive pattern.
- Once you delegate, commit to it. Don't redo the subagent's work or re-derive its findings while it runs.
Each of those has an incident behind it.
Nine research agents, one usage window. On a research job for a game project, nine agents ran in parallel for about ninety minutes, hit the usage limit together, and exactly one partial notes file had reached disk. Resuming them failed. The work was not actually gone: every search, fetch and file read is recorded in each agent's task transcript. We scripted the extraction, recovered 1,410 sources and about 5 MB of text from the nine transcripts, and had small fresh agents digest it. That cost roughly a tenth of the original run. The lasting rules: tell any long-running research agent to write its notes file before its first web call and re-save after each section, and prefer many small-context agents to a few that grow huge.
Ten agents, zero bytes free. A ten-agent run doing image-heavy work, alongside video encoding and a headless browser, pushed memory into swap on an 18 GB laptop. Swap shares the disk with everything else, so free space went from 7.9 GB to nothing and the shell stopped responding until the run was stopped. Before a wide fan-out we now check free disk space and current swap use, and cap concurrency when there is less than about 10 GB free.
Two screens that passed alone. Two agents each built one screen of an interface against their own test page. One passed 483 checks. Mounted in the same document, the header of one was garbled by the other's stylesheet, which used bare class names such as .cell and .title. The brief now says to root every selector at the component's own class, and the first check after integration is a scripted walk of the combined page. Results from separate harnesses do not transfer.
None of this argues against subagents. A fan-out has a budget: tokens, memory, disk, and your attention when the reports come back.
Subagents vs skills vs agent teams
The documentation lists several ways to run work in parallel. These three get confused most.
| Subagent | Skill | Agent team | |
|---|---|---|---|
| What it is | A worker Claude starts for one task | Instructions Claude follows | A lead session supervising peer sessions |
| Context | Its own window | The conversation you are in | Each teammate has its own |
| Who it reports to | The conversation that started it | Nobody; it is the conversation | Teammates message each other and share a task list |
| Status, November 2026 | Standard | Standard | Experimental, off by default |
| Use it when | Output would flood your context, or you want enforced tool limits | You want your procedure followed with full context | Workers need to discuss and coordinate |
Subagents vs skills. Skills change how Claude works on the task in front of it. Subagents move a task somewhere else. If your problem is "Claude keeps doing this step wrong," you want a skill. If it is "this search buried my conversation," you want a subagent. We go through all three in Claude Code skills vs subagents vs hooks.
Subagents vs agent teams. Agent teams are enabled by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, and the docs warn of known limitations around session resumption, task coordination and shutdown. The same page says teams "use significantly more tokens than a single session." This is documentation only: we have not run agent teams in production, and we would exhaust subagents first.
For work that outgrows a handful of subagents, the documented next step is a dynamic workflow, where a script holds the plan. That is the subject of our Claude Code workflow guide.
A checklist before you delegate
- Could I finish this in a few tool calls? Then do it here.
- Is the task independent? If it needs back-and-forth with you or shares files with other work, keep it in the main conversation or isolate it in a worktree.
- Is the brief complete on its own? Goal, files to read, what is already ruled out, the format of the answer. The subagent knows nothing else.
- Have I asked for a short report? Twenty long reports fill your context as surely as doing the work would have.
- Does it need this model? Simple collection jobs belong on a smaller one.
- Are the tool limits in the file? A limit in a prompt is a request. A limit in
toolsis enforced. - Will its notes survive a crash? Long research writes to disk as it goes.
- Is there room to run it? Check usage headroom, memory and disk before a wide fan-out. Running
/usageshows what share each subagent type is taking.
Claude Code subagents are a context tool that happens to run in parallel. Every delegation is a purchase: tokens and visibility, in exchange for a cleaner conversation and sometimes speed. For a wider view of how we work with the tool day to day, see how to use Claude Code effectively and our earlier piece on Claude Code in web development.
If you want agents doing real work inside your business and would like the guardrails designed by people who have tripped over them, that is what our AI integration service is for. Tell us what you are trying to automate.
Common questions
What are Claude Code subagents?
A subagent is a worker that Claude Code starts inside your session to handle one task in its own context window. It gets its own system prompt, its own tool list and, optionally, its own model, does the work, and returns a summary to the main conversation. The point is context: a wide search or a long test run stays in the subagent's window, not yours. Its requests still count toward the same usage limits as the main conversation, so a subagent saves context, not tokens.
How to create a subagent in Claude Code?
Create a Markdown file with YAML frontmatter in .claude/agents/ inside a project, or in ~/.claude/agents/ to have it in every project. Only name and description are required; the body of the file becomes the subagent's system prompt. You can also ask Claude to write the file for you. As of November 2026, Claude Code picks up new and edited files within a few seconds, except when the agents directory did not exist when the session started, in which case you restart once.
What are some Claude Code subagents examples?
The built-in ones are the best examples: Explore is a read-only codebase searcher, Plan gathers context in plan mode, and general-purpose handles multi-step tasks that need both reading and editing. Useful custom ones tend to be narrow: a reviewer that can only read, a link checker on a small model, a test runner that returns only the failures, a research agent that writes notes to a file. If you cannot describe the job in one sentence, it is probably not a subagent yet.
What are Claude Code subagents best practices?
Delegate only work that is large, independent and able to run in parallel. Write the brief once and make it complete, because the subagent starts with none of your conversation. Ask for a short summary back. Restrict tools in the definition file instead of asking politely in the prompt. Put simple jobs on a smaller model. Tell long-running research agents to save notes to disk as they go. And do not spawn a subagent to check the work you just did yourself.
Claude Code subagents vs agent teams: what is the difference?
Subagents work inside one session and report back to the conversation that started them. Agent teams are several full Claude Code sessions, with one acting as lead, that share a task list and message each other directly. As of November 2026 the documentation marks agent teams as experimental and disabled by default, and says they use significantly more tokens than a single session. Use subagents when only the result matters. We have not run agent teams in production, so that part is from the documentation.
How does Claude Code subagents model selection work?
Set the model field in the definition file to an alias such as sonnet, opus or haiku, a full model ID, or inherit. If you leave it out, the subagent runs on the same model as the conversation that started it. Claude Code resolves the model in this order: the model parameter Claude passes when it starts the subagent, then the definition's model field, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation's model. Check the current docs for which aliases your plan offers.
Claude Code subagents vs skills: which should I use?
A skill is a set of instructions loaded into the conversation you are already in. A subagent is a separate worker with a separate context window. Use a skill when you want Claude to follow your procedure with everything it already knows about the task. Use a subagent when the work would flood the conversation with output you will not need again, or when you want enforced limits such as read-only tools. They combine: a subagent definition can preload skills through its skills field.

