Claude Code subagents: how to create and use them

What are subagents in Claude Code?

Per the official subagents page, a subagent is a specialized AI assistant for one type of task. Use one when a side task would flood your main conversation with search results, logs or file contents you will not reference again: the subagent does that work in its own context and returns only a summary. Define a custom subagent when you keep spawning the same kind of worker with the same instructions.

Each subagent has its own context window, system prompt, tool access and permissions. It also sends its own requests, which count toward the same usage limits as your main conversation. Claude reads each subagent's description to decide when to hand it work, so the description is the most important line in the file.

Subagents work within a single session. If you need several independent sessions that coordinate, that is the job of agent teams, which are a separate, experimental feature.

Which subagents come built in?

Claude Code includes built-in subagents that Claude uses automatically when appropriate. Each inherits the parent conversation's permission rules, and most run with a restricted tool set.

Explore and Plan start without your CLAUDE.md files and the git status snapshot to stay fast and cheap. A user or project subagent named Explore overrides the built-in one, so you can define your own with model: haiku to run exploration on a cheaper model. To remove only Explore and Plan, set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1.

How do you create your first subagent?

Subagents are Markdown files with YAML frontmatter. The quickest route, and the one the docs use, is to ask Claude to write it for you:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude writes ~/.claude/agents/code-improver.md. Open it and check that the frontmatter matches what you asked for. The result looks like this:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Then try it: "Use the code-improver agent to suggest improvements in this project". In the transcript the delegation shows as a row such as code-improver(Suggest code improvements).

Two practical notes from the docs. Claude Code watches ~/.claude/agents/ and .claude/agents/, so edits take effect within a few seconds with no restart, but the watcher only covers directories that existed when the session started. If you create the first agent file in a brand-new agents directory, restart. And /agents no longer opens a wizard: on current versions it prints a reminder to ask Claude or edit the folders directly (the interactive wizard was removed after v2.1.197).

Where do subagent files live?

A subagent's location decides who can use it. When two share a name, the higher-priority location wins.

Both directories are scanned recursively, so you can group files in folders such as agents/review/. Identity comes only from the name field, not the path, so keep names unique. Plugin subagents are namespaced instead: agents/review/security.md in plugin my-plugin registers as my-plugin:review:security. For security, plugin subagents ignore the hooks, mcpServers and permissionMode fields; see the plugins guide.

For a throwaway or scripted agent, pass JSON when launching. It exists only for that session:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

What can you put in a subagent's frontmatter?

Only name and description are required. Multi-word fields use camelCase, such as maxTurns and disallowedTools, and a field Claude Code does not recognize is ignored without an error. If a field seems to do nothing, run claude --debug and search the debug log for does not recognize or apply.

A few of these deserve a sentence. memory gives the subagent a directory that survives across conversations: user stores it under ~/.claude/agent-memory/<name>/, project uses .claude/agent-memory/<name>/ and can be committed, and local uses .claude/agent-memory-local/<name>/. The docs call project the recommended default. skills is different from a skill that runs in a subagent; see the skills guide. And mcpServers scopes tools to one agent, covered in the MCP guide.

Keep descriptions short. When the combined descriptions of your non-built-in subagents exceed 15,000 tokens, Claude Code warns at startup and still loads every one. Move detail into the system prompt, which only loads when that subagent runs.

How do you limit what a subagent can do?

Use tools as an allowlist or disallowedTools as a denylist. If both are set, disallowedTools applies first. The limit is enforced by Claude Code, not requested in a prompt, which is why it is the right way to build a reviewer that cannot edit anything.

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

That file is the example in the official best practices page. MCP tools can be scoped too: mcp__github__* in tools gives the subagent every tool from one server, and mcp__* in disallowedTools withholds every MCP tool. Some tools are never available to subagents regardless of the list, including AskUserQuestion, EnterPlanMode and Workflow.

To block specific commands while keeping Bash, add a Bash deny rule to permissions.deny, which applies to the main conversation and every subagent. Background subagents also run with a smaller built-in tool set than foreground ones.

Which model does a subagent use?

Claude Code resolves a subagent's model in this order, per the docs:

1. The per-invocation model parameter, if Claude passes one.
2. The model field in the subagent's frontmatter (inherit selects the main conversation's model).
3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable, when set to an alias or model ID.
4. The main conversation's model.

Routing simple work to a cheaper model is the main cost lever. The best practices page suggests model: haiku for jobs such as collecting the files that import a module or checking links, and notes that subagents mostly cost tokens: each sends its own requests, and a fresh subagent first has to gather context your conversation already had, so it can end up slower than doing the task where you are. To force one model onto every subagent, set CLAUDE_CODE_SUBAGENT_MODEL and CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 together. Run /tasks while a subagent is working to see the model on its row.

How do you call a subagent yourself?

Claude delegates on its own based on descriptions. Adding a phrase such as "use proactively" to a description encourages that. When you want control, the docs describe three escalating patterns:

You can also type the mention without the picker as @agent-<name>. To make an agent the default for a project, set "agent": "code-reviewer" in .claude/settings.json; the CLI flag wins if both are present. Note that a session started with --agent replaces the default Claude Code system prompt with the agent's own prompt, though CLAUDE.md files still load.

Do subagents run in the foreground or the background?

With nothing configured, a subagent Claude spawns from your main conversation starts in the background, so you keep working. Permission prompts from a background subagent surface in your main session and name the subagent asking: approve to continue, or press Esc to deny that one tool call. A foreground subagent blocks the conversation until it finishes.

Claude cannot wait for a subagent while fork mode is on, which is the default in interactive terminal sessions. To let Claude wait, set CLAUDE_CODE_FORK_SUBAGENT to 0 in the env block of settings and start a new session, then ask, for example, "run the reviewer subagent and wait for its report". Press Ctrl+B to move a waiting task to the background. Finished subagents stay listed in /tasks for 30 seconds.

• Nesting: a subagent can spawn its own subagents up to three layers below the main conversation by default. Change it with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; 1 turns nesting off.
• Concurrency: when 20 subagents are running, spawning another fails with Concurrent subagent limit reached. Change it with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
• Forks: /subtask <task> starts a fork, a background subagent that inherits your whole conversation instead of starting fresh. Use it when any other subagent would need too much background. A fork shares the main session's prompt cache, so it costs less than a fresh subagent for tasks needing the same context.

When should you use a subagent instead of the main conversation?

The docs make a point worth repeating: handing the same task to a subagent does not make the answer better. A fresh reviewer helps because it has not seen your reasoning, which is different from delegating. For a question about something already in your conversation, use /btw instead, which sees your full context but has no tool access.

Use a subagent to run the test suite and report only the failing tests with their error messages

Research the authentication, database, and API modules in parallel using separate subagents

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

use a subagent to review the diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style

Subagents suit projects with a real codebase. If you are still choosing what to build, browse developer tools ideas on the board, or read the guide to building an app with Claude Code for the full loop.