Guide

How to use subagents in Claude Code

Long searches and noisy test output fill up your Claude Code conversation fast. Subagents take that work into a separate context and hand back a summary. This guide explains what they are, how to make your own, and when they are worth it.

Updated 30 October 2026

Quick answer: a subagent is a specialized helper that Claude Code hands a task to. It works in its own context window with its own instructions and tool access, then returns only a result. To create one, save a Markdown file with a name and description in its frontmatter to .claude/agents/ (one project) or ~/.claude/agents/ (all projects), then ask Claude to use it by name or pick it with @.

Details below come from Anthropic's Claude Code documentation as of October 2026. Claude Code changes often, so run claude update if something described here is missing.

What subagents are

When Claude meets a task that matches a subagent's description, it can delegate it. The subagent starts fresh: it does not see your conversation, only the instructions Claude passes along. It does its work, such as reading dozens of files or running a test suite, and sends back a summary. Your main conversation stays short.

Claude Code ships with built-in subagents, including:

Explore: fast, read-only search and analysis of a codebase.
Plan: read-only research while you are in plan mode.
General-purpose: multi-step tasks that need both exploring and changing things.

You don't have to set these up; Claude uses them when they fit.

Create your own subagent

Decide the scope. For a subagent the whole team can use in one repository, create the folder .claude/agents/ in the project. For one that follows you across projects, use ~/.claude/agents/.
Create a Markdown file in that folder, for example code-reviewer.md.
Start the file with frontmatter between two --- lines. The first line of the file must be ---.
Add the two required fields: name (a unique identifier, for example code-reviewer, without a colon) and description (when Claude should use it, for example Reviews code for quality and best practices. Use after code changes.).
Optionally add tools to limit what it can use, for example Read, Glob, Grep for a read-only reviewer, and model (a model alias such as sonnet or haiku, a full model ID, or inherit).
Below the closing ---, write the subagent's instructions in plain language: its role, what to check, and what to return.
Save the file. Claude Code picks up changes in an existing agents folder within seconds; if you created the folder during the session, restart Claude Code.

You can also just ask Claude in a session to create a subagent for you. In current versions, the /agents command points you to exactly that, or to editing the folders directly.

Use a subagent

Let Claude choose: Claude compares your request with each subagent's description. Words like "use proactively" in the description encourage it to delegate.
Ask by name: for example Use the code-reviewer subagent to check my recent changes.
Mention it: type @ and pick the subagent. This guarantees that subagent handles the task.
For a whole session: run claude --agent code-reviewer.

When subagents help, and when they don't

Anthropic's guidance boils down to this:

Use a subagent when	Stay in the main conversation when
The task produces lots of output you don't need to keep, like logs or search results	You need frequent back-and-forth
You want to restrict which tools can be used	Several steps share a lot of context
The work is self-contained and can end in a summary	It's a quick, targeted change
You want independent research to run in parallel

Good to know

If two subagents share a name, the higher-priority location wins: managed settings, then the --agents flag, then the project folder, then your user folder, then plugins.
A subagent doesn't see your chat history or files Claude already read, so it relies on the instructions Claude gives it.
By default up to 20 subagents can run at the same time.
Field names are camelCase (for example disallowedTools, maxTurns), and unrecognized fields are silently ignored, so check spelling.
Project subagent files can be committed, so the whole team gets the same helpers.

If it doesn't work

Claude doesn't find the new subagent: if the agents folder didn't exist when the session started, restart Claude Code.
The file is skipped silently: common causes are a missing name or description, invalid YAML, or --- not on the first line. Run claude --debug and read the debug log, or run claude plugin validate .claude/agents to find files whose frontmatter doesn't parse.
Claude reports an error naming unresolved tools: when none of the entries in tools match a real tool, Claude Code usually won't launch the subagent. Fix the spelling of the tool names.
Wrong model: run /tasks to see which model each subagent actually uses.

Keep the results, not just the summary

A subagent's report ends up in your session, which is gone from view once the session closes. With the Workbranch plugin for Claude Code, saying "save this to Workbranch" files the tasks, decisions and open questions from the session into a project, and the next session in that folder starts with what is still open. See Workbranch for Claude. If a session ran out of room, resuming a Claude Code session covers how to get back in.

Sources

Use Claude Code with your Pro or Max plan (Claude Help Center, checked 30 October 2026)
Create custom subagents (Claude Code docs, checked 30 October 2026)

Frequently asked questions

Do subagents use extra usage?

Subagent requests count toward the same usage limits as your main conversation. Routing simple work to a cheaper model such as Haiku through the model field can keep costs down.

Can a subagent start its own subagents?

Yes, by default up to three levels below the main conversation. To stop one particular subagent from doing so, leave Agent out of its tools list.

Can I run a whole session as a subagent?

Yes. Start Claude Code with claude --agent followed by the subagent's name, and the session uses that subagent's prompt, tools and model.