Claude Code subagents: how to create them, when Claude uses them, and what they cost

A Claude Code subagent is a helper Claude starts for a side task: it runs in its own context window, with its own prompt, tools and model, and hands back only a summary. Claude Code ships several built in, and you add your own as Markdown files in .claude/agents/. Its requests count against the same plan limits as the main conversation.

What a subagent is

The subagent gets a delegation message Claude writes for it — not your conversation, not the files Claude has read. It works in a fresh context, and only its final summary comes back into yours. That is the point: a search through forty files, or a test run with pages of output, stays out of the main context.

It loads your CLAUDE.md files and a git status snapshot; Explore and Plan skip both, and a subagent with omitClaudeMd: true skips your CLAUDE.md. It does not get your output style or auto memory. Its transcript is a separate file, ~/.claude/projects/<project>/<session-id>/subagents/agent-<id>.jsonl, deleted with the session after 30 days by default.

The built-in subagents

To turn one off, deny it in settings — "deny": ["Agent(Explore)"] — or set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 to drop Explore and Plan. Denying Agent stops all delegation.

Create a subagent

A subagent is a Markdown file with YAML front matter; the body is its system prompt. Ask Claude to write one ("Create a code-reviewer subagent in .claude/agents/ that is read-only and uses Sonnet"), or save it yourself:

---
name: code-reviewer
description: Reviews code quality. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Save it as .claude/agents/code-reviewer.md to share it with the repository, or under ~/.claude/agents/ for every project. Both folders are read recursively, so agents/review/ works; the name field, not the file name, is what you call it by. When two share a name, the higher one wins: managed settings, then --agents, then the project folder, then your user folder, then plugins.

/agents no longer opens a wizard (since Claude Code 2.1.198); it reminds you to ask Claude or edit those folders. If a new user subagent is not found, restart: a running session does not notice an agents folder created after it started.

For one session only, pass JSON on the command line — prompt is the body:

claude --agents '{"code-reviewer": {
  "description": "Expert code reviewer. Use proactively.",
  "prompt": "You are a senior code reviewer...",
  "tools": ["Read", "Grep", "Glob", "Bash"],
  "model": "sonnet"}}'

Frontmatter fields

Only name and description are required. A misspelt field is ignored without an error, so maxturns does nothing; field names are camelCase.

permissionMode only counts when the main conversation is in Manual (default), dontAsk or plan mode. If the main conversation is in bypass, accept edits or auto mode, the subagent runs in that mode instead, and a subagent set to bypassPermissions gets it only when the main conversation already has it. Under auto mode the classifier checks the subagent's actions and its report before the parent reads it; see Claude Code auto mode, and for bypass, claude --dangerously-skip-permissions.

The model is picked in this order: the model Claude passes for that call, the front matter, CLAUDE_CODE_SUBAGENT_MODEL, then the main conversation's model. With CLAUDE_CODE_SUBAGENT_MODEL set, adding CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 puts that model on every subagent, Explore and Plan included; forks stay on the main model.

How Claude decides to use one

Claude delegates on the strength of your request and each subagent's description. Put "use proactively" in a description to make it reach for that subagent more often. Keep descriptions short: past 15,000 tokens for all of yours together, Claude Code warns at start-up. To be sure one runs, mention it:

--agent replaces Claude Code's system prompt with the agent's. To make it the default in a project, set "agent": "code-reviewer" in .claude/settings.json.

Background, parallel and nested subagents

• Background by default: in an interactive session fork mode is on (since 2.1.232), so every subagent Claude starts runs in the background while you keep typing. Ctrl+B sends a running task there. With -p and in the Agent SDK, Claude runs one in the foreground when it needs the result first.
• Permission prompts from a background subagent come to your main session and name the subagent asking. Esc denies that one call without stopping it.
• Parallel: "Research the authentication, database, and API modules in parallel using separate subagents." Up to 20 run at once by default (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS); there is no cap on how many run over a session.
• Nested: a subagent can start its own, up to three levels below the main conversation; CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 turns that off.
• Resumed: Claude can send a finished subagent a follow-up, and it keeps its history. Explore and Plan cannot be resumed.
• Gone from the panel: a subagent that finishes successfully leaves the panel at once, and stays in /tasks for 30 seconds, where Enter opens its transcript.

Subagents worth writing, and how to keep them useful

Anthropic's own examples are a code reviewer, a debugger, a data scientist and a database query validator. What they share:

• One job each, with a description that says when to use it, not what it is.
• The fewest tools that do the job. A reviewer needs Read, Grep, Glob; leave Agent out of tools if it should not start subagents of its own.
• The cheapest model that does the job. Anthropic suggests model: haiku for simple subagents.
• A subagent for output you will not read. Test runs, log searches and doc fetches; keep work that needs back-and-forth in the main conversation.
• Rules restated in the delegation. The subagent sees your CLAUDE.md, not the conversation, so "ignore vendor/" said earlier does not reach it.

Subagents, skills, forks and agent teams

• A skill adds instructions to your main context; a subagent works in a context of its own and returns a summary. A subagent can preload skills. More in Claude Code skills.
• A fork (/subtask <task>, since 2.1.212) inherits the whole conversation and shares its prompt cache, which Anthropic calls cheaper than a fresh subagent for work that needs the same context.
• Agent teams are separate sessions managed by a lead that message each other directly, experimental and off by default, at about 7× the tokens of a standard session when teammates run in plan mode. Subagents report only to the conversation that started them. The ways to run agents side by side: Claude Code multiple agents.

What subagents cost

Anthropic's docs say each subagent sends requests of its own, against the same limits, and on Pro, Max, Team and Enterprise plans /usage shows the subagents' share of recent usage as a percentage. They give no per-subagent figure. Here is one machine's, read from Caprock's export on 4 October 2026: every Claude Code call from 18 July to 4 October, one row per API message, priced at Anthropic's list prices.

47%

of Claude Code calls were made by subagents

14%

of the list-price cost: $2,068 of $14,338

$0.59

a median subagent, start to finish

Subagents made 40,027 of 85,964 calls but cost far less per call: the median subagent call carried 62K tokens of context, the median main-thread call 426K. A fresh context is a small one. 1,685 subagents ran, in 30 of 98 sessions. This is one heavy user's machine and mostly Opus; it is not a benchmark, and it is not a bill.

See every subagent, and read what it answered

In Claude Code, the panel under the prompt shows the subagents running now, and a finished one leaves /tasks after 30 seconds. After that it is a JSONL file on disk with no total. Caprock reads those transcripts, nested ones included, and keeps each call with its subagent:

⤢

⤢

• Live: the session's side panel lists its subagents under Subagents · N, in the order they started: what each is doing now, and under it the figures you pick with Show (cost and time by default; calls, cost, model and time on Full), with waiting on you when its prompt is open. A finished one stays in its place, dimmed with a ✓. A chip per subagent sits at the bottom of the panel's top block, in groups of five.
• Open one: click its row to read the task the parent gave it, every call it made with how long each took and the failed ones marked, what it answered, and its model, time, tokens, cost and costliest tools. Finished subagents open too; +N finished lists them.
• Cost: a subagent's calls count in the session that started it, at list prices. A call Caprock cannot price is left out, not shown as $0.
• Your own numbers: caprock export has a subagent_id column, which is how the figures above were read.

$ caprock export --agent claude --since 90d --out events.tsv

It keeps them after Claude Code's 30-day cleanup, for every session on the machine whether or not it started it. Free, open source; nothing leaves your machine. Install Caprock.