Claude Code subagents, and when to use one

What is a subagent in Claude Code?

Anthropic describes a subagent as “specialized AI assistants that handle specific types of tasks”. The reason to reach for one is in the same paragraph: use a subagent when a side task would flood your main conversation with search results, logs or file contents you will never refer to again. The subagent does that work in its own context window and returns only the summary, so your main conversation stays about the task rather than about the looking.

Three things are the subagent's own, and they are what make it more than a second prompt. It has its own context window, which starts without your conversation history: it gets the task Claude hands it, plus your CLAUDE.md files and a git status snapshot. It has its own system prompt, taken from the subagent's own definition rather than Claude Code's. And it has its own tool access and permissions, so you can hand it a read-only job and be sure it cannot write. It also sends its own requests, which count toward the same usage limits as your main conversation.

A subagent lives inside one session. That is the boundary this page stays behind: Claude Code also documents routes for work that spans several sessions — background agents, cross-session messaging and agent teams — and this page is not about those. Further down is the plain version of the difference.

You do not have to name one. Claude delegates on its own when a task matches a subagent's description, and to encourage that you put a phrase like “use proactively” in the description field. Naming one anyway is covered under how to create a subagent.

The descriptions are not free. Claude Code shows a warning at startup when your subagents' combined descriptions, except the built-in ones, pass 15,000 tokens, and it still loads every subagent. The fix it suggests is to trim the description fields and move the detail into each subagent's system prompt, which only loads when that subagent runs.

The subagents Claude Code ships with

Claude Code includes built-in subagents and uses them on its own where they fit. Each inherits the parent conversation's permission rules, and most run with a restricted tool set. They are registered by default in interactive sessions, so there is nothing to switch on.

Explore and Plan start without your CLAUDE.md files and the git status snapshot, so research stays fast and cheap. Every other built-in and custom subagent loads both, unless a custom one sets omitClaudeMd, which starts it without your user, project and local CLAUDE.md files.

If you would rather Claude did not use them, you have four levers, and they are not the same lever. Add one type to permissions.deny to block that type. Deny the Agent tool itself to stop delegation altogether. Set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 to remove only Explore and Plan, which needs Claude Code v2.1.198 or later, and leaves Claude reading and exploring files directly. And in non-interactive mode or the Agent SDK, CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 removes every built-in type so only yours remain.

How to create a subagent

There is a command, and it is worth knowing what it does today. Running /agents prints a reminder to ask Claude to write the subagent or to edit the agents directories yourself. On Claude Code v2.1.197 and earlier, /agents instead opens an interactive wizard with a Running tab listing live subagents and a Library tab for creating, editing and deleting them. On a current build, the two paths are writing the file yourself and asking Claude to write it for you.

Where a subagent file lives

A subagent is a Markdown file, and its location decides who can use it. When two definitions share a name, the higher-priority location wins.

Inside a project, Claude Code walks up from your working directory, so every .claude/agents/ between there and the repository root is scanned and the definition closest to your working directory wins. Both directories are also scanned recursively, so you can organise definitions into subfolders such as agents/review/. The subdirectory is not part of the subagent's identity: the name field is. Keep names unique across the whole tree, because two files under one agents directory that declare the same name leave Claude Code loading whichever it reads first.

What is in the file

The file is YAML frontmatter between --- markers, followed by the system prompt in Markdown. Only two fields are required: name and description. The body becomes the subagent's system prompt, and it is the whole of it — a subagent receives its own prompt plus basic environment details such as the working directory, not Claude Code's system prompt.

---
name: test-runner
description: Runs the test suite and reports only failures. Use proactively after changing code.
tools: Read, Grep, Glob, Bash
model: haiku
---

You run this project's tests and report results. Run the suite for the area
that changed, then read the failing output and report each failure as: the
test name, the assertion that failed, and the file and line it points at.
Do not fix anything. Return the failures as text rather than writing a file.

Save that as .claude/agents/test-runner.md in your project, or ~/.claude/agents/test-runner.md to have it everywhere. Claude Code watches both directories, so an edited file is picked up within a few seconds and the next delegation uses the new definition. Three cases still need a restart: a directory that did not exist when the session started, an agents directory inside a path you added with --add-dir, and a session started with --disable-slash-commands, which watches neither.

To see it run, ask for it by name — “use the test-runner subagent to find why the suite fails” — or type @ and pick it from the typeahead, which guarantees that subagent runs for one task. Your full message still goes to Claude, which writes the subagent's task prompt from what you asked.

The settings that matter most

Beyond the two required fields, a handful do most of the work. Multi-word field names are camelCase, and Claude Code ignores a field it does not recognise without telling you.

The model field is resolved in a fixed order. First the model Claude passes for that one invocation, then the subagent's own model frontmatter — where inherit means the main conversation's model — then the CLAUDE_CODE_SUBAGENT_MODEL environment variable when you have set it, and failing all of those, the main conversation's model. To put every subagent on one model, set CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1 alongside it, which needs Claude Code v2.1.257 or later. An alias in that variable always resolves to the version it points to, while the same alias in frontmatter can resolve to the main conversation's exact model when they share a family.

Tool access is worth being exact about, because it is the usual reason to write a subagent at all. A subagent inherits the built-in and MCP tools available in the main conversation, and two filters narrow that. The first removes a short list from every subagent whatever you list — AskUserQuestion, EnterPlanMode, ScheduleWakeup, Workflow and a few more. The second applies to subagents running in the background, which keeps every MCP tool but only a named set of built-in ones, so the same definition can resolve to different tools in the foreground and the background. Both fields also take whole-server entries such as mcp__github__*.

One trap when you want a subagent that only reads: a disallowedTools entry with a specifier, such as Bash(git push *), still removes the whole Bash tool rather than the matching commands. To keep Bash and block the push, put that pattern in permissions.deny in your settings instead, where it applies to the main conversation and the subagent alike.

When subagents help

Anthropic's own list of what subagents do for you is short and worth reading before you write one: they preserve context by keeping exploration and implementation out of the main conversation; they enforce constraints by limiting which tools a subagent can use; they reuse a configuration across projects when the file is user-level; they specialise behaviour with a focused system prompt; and they control cost by routing a task to a faster, lower-cost model such as Haiku.

Anthropic's page puts the rule for choosing this way: use a subagent when the task produces verbose output you do not need in your main context, when you want to enforce specific tool restrictions or permissions, and when the work is self-contained enough to return a summary. Use the main conversation instead when the task needs frequent back-and-forth, when several phases share significant context such as planning, implementation and testing, when you are making a quick targeted change, or when latency matters — a subagent that is not a fork starts fresh and may need time to gather context.

Two documented patterns are worth copying. Isolate a high-volume operation: “use a subagent to run the test suite and report only the failing tests with their error messages”. And run research in parallel: ask for the authentication, database and API modules to be researched at once by separate subagents, each exploring its own area, with Claude synthesising the findings. That second one works best when the research paths do not depend on each other.

If the question is about something already in your conversation, none of this applies. Anthropic points at /btw for a side question: it sees your full context, has no tool access, and its answer is not added to your history. That is the cheap option, and a subagent is the expensive one you reach for when the work has to happen away from your context.

Subagents or skills?

Anthropic draws the line between them in one sentence: consider skills instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context. A skill is a file of instructions; a subagent is a separate worker with its own window. Reach for the subagent when the work has to happen away from your context, and for the skill when the instructions belong in it.

The two also meet, in both directions, and two rows are the whole of it.

The first row is how you send a skill into a subagent. Add context: fork to the skill's frontmatter and Claude Code starts a new subagent of the type named in its agent field — Explore, Plan, general-purpose or any custom subagent, defaulting to general-purpose — and hands it the skill's content as its prompt. That subagent does not see your conversation, so the skill has to stand on its own, and Anthropic warns that a skill holding guidelines but no task returns nothing useful. Despite the name it is not a fork of your conversation, and it runs in the background by default unless the skill sets background: false. The second row is the inverse: a subagent's skills field preloads skill content into it at startup.

When a subagent costs you more

The first cost is the one people miss. A subagent is not free context: it sends its own requests, and those count toward the same usage limits as your main conversation. Delegating work does not move it outside your plan; it adds a second stream of requests to it.

The second is context, and Anthropic flags it directly. When subagents finish, their results return to your main conversation, so running many that each return detailed results can consume significant context — and each subagent spends tokens of its own while it runs. A subagent that returns two lines has saved you everything it read; one that returns its whole transcript has handed the pile back to your context anyway.

The third is the fresh start. A subagent that is not a fork does not see your conversation history, the skills you have invoked, or the files Claude has already read. It works from a delegation message Claude writes, so it may re-read things the main conversation already had. It does load your CLAUDE.md files and a git status snapshot — Explore and Plan skip both — and its context window is sized by its own model, so delegating to a model with a smaller window gives that subagent the smaller window. And because it starts without your conversation, your output style does not shape its replies and a rule you rely on has to be restated in the delegation prompt if the subagent itself needs it.

There is a limit on how many Claude spawns at once. By default, when twenty subagents are running in a session, spawning another fails with Concurrent subagent limit reached and the error tells Claude not to retry; spawning works again once the count drops below the limit. Resuming a finished subagent takes a fresh slot without checking the limit, so a resume can push the running count past it. Set CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to any positive whole number to change it, and note that sessions with ultracode active are exempt. Nothing limits the total number a session spawns across its life, only how many are in flight.

Subagents can also spawn subagents. By default that nests up to three layers below the main conversation, and at the limit Claude Code withholds the Agent tool so the subagent does its delegated work itself. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH changes the depth, and setting it to 1 turns nesting off. If you want one subagent that must not delegate — a reviewer that should stay read-only, say — leave Agent out of its tools list or add it to disallowedTools, because a subagent that can spawn is a subagent whose cost you did not budget.

One thing the documented surface does not list is a spend cap for a single subagent. There is no documented money budget for one subagent, and the limits that do exist bound other things: maxTurns stops it after a number of turns, the concurrent limit caps how many run at once, and the depth limit caps how deeply they nest. There is also no per-subagent thinking setting: from v2.1.198 a subagent inherits the main conversation's extended thinking configuration, on when yours is on and off when yours is off.

Two smaller points to finish on. Explore and Plan are one-shot and return no agent ID, so Claude cannot resume them; if you will want to continue the work, use general-purpose or a subagent you wrote. And a subagent's report is scanned before Claude reads it, because a subagent may have read files, pages or command output you never reviewed. The scan adds a backslash to text imitating Claude Code's own output and prepends a marker line when a report matches an instruction-shaped pattern. It never removes or rewords anything, and it does not judge whether content is malicious.

What people have reported

Searching Anthropic's own issue tracker for subagent reports on October 24, 2026 returns 2,010 issues with “subagent” in the title. A few of them are worth reading before you build a chain of subagents, because each one names a cost that is easy to walk into. Every report below is named by the person who filed it, with the day they filed it, and links to the issue.

That list is a report stream, not a changelog: an issue filed in June and still open does not by itself describe the build you are running, and the two oldest entries here have since been closed. And a report is one person's setup — the MCP report above is what happens when a subagent inherits a very large tool pool, which is a real warning about writing subagents against many servers, not a general statement about subagents. Anthropic's own docs remain the reference for what Claude Code does now.

This is not the same as several sessions

These two get mixed up, and the difference is simple. A subagent runs inside one session. Claude spawns it, it works in that session's working directory unless its own definition sets isolation: worktree, and its results come back inside the same conversation. Its transcript is stored under that session rather than as a conversation of its own: while its row is still in the subagent panel or /tasks you can type into its transcript, and after a restart the route back is to resume the session it belongs to. Its value is that the work stays out of your context while you stay in charge of one thread.

A separate session is a conversation of its own, with its own context window, its own model choice, its own permissions and its own transcript that you can come back to. Nothing about it is scoped to the conversation you started it from. Anthropic's own advice on when to cross that line is explicit: for work that needs to keep running in parallel or will not fit in one context window, run it in separate sessions instead.

We cover that side of the line elsewhere, and none of these pages re-runs this one: parallel agents maps every route Claude Code documents, running multiple sessions is the practical version, and running many coding agents is what a shared working copy does at scale.

Where Omniscio fits

Plainly: Omniscio does not manage Claude Code's subagents. Subagents are Claude Code's own mechanism, inside one session, and a definition you write lives in your Claude Code agents directory and runs there. If you want subagents, write the file — nothing on this page needs Omniscio.

What it can do is show you one happening. With showSubagentActivity on — it is off by default — a session shows a chip once Claude has had subagents running for about fifteen seconds, and a collapsible card in the transcript as each one finishes, errors expanded and successes folded away.

Where Omniscio sits is one level up, at the sessions those subagents run inside. It is a desktop app for running Claude Code and other agent harnesses side by side, built around one calm inbox rather than a wall of terminals: agents alert you only when a decision actually needs you. Any model, any harness — Claude Code, Codex, OpenCode, Devin, Pi, and Hermes all supported.

Two things worth knowing before you assume a default from that. Per-session git worktree isolation ships off and is switched on for one session, one project or the whole app; the exception is a harness that auto-approves every tool call, which is isolated by default in a git repository. And the per-session spend cap is for metered model keys and Omniscio credits: a subscription session, on a Claude Pro or Max plan, is never spend-capped. The free plan covers 8 projects and 10 agents at once, and Pro is $20/month or $192/year.

A subagent's tokens are counted into the token totals of the session that launched it, so its work shows up in that session's own figures. If you want the wider picture, the parallel-agents guide covers the session routes and the library covers how one session gets its own copy of a project.