What is a subagent in Claude Code?

A separate Claude that your session starts for one task. It has its own context window, its own instructions and only the tools it is given. It works through the task, then hands back a short summary, so the files it read and the output it saw never fill your main conversation.

How do I create a custom subagent?

Ask Claude to write one, such as "create a read-only test-runner subagent in .claude/agents/ that uses Sonnet", or write the file yourself - a Markdown file with name, description and optional tools and model between --- lines, and the subagent's instructions below.

How do I make Claude use a particular subagent?

Name it in your message ("use the code-reviewer subagent on my changes"), or type @ and pick it so it is sure to run. To make a whole session run as that subagent, start with claude --agent code-reviewer.

Do subagents cost more?

Each subagent sends its own requests, which count against the same usage limits as your main conversation, and several running at once add up quickly. They can also save money when you give a simple job to a cheaper model such as Haiku, and they keep your main conversation smaller.

What is the difference between a subagent and a skill?

A skill is instructions that run in your current conversation. A subagent runs in its own separate context with its own tools and returns only its result. Use a skill for a procedure you want to watch, and a subagent for a self-contained job whose working steps you do not need.

Claude Code subagents: what they are and how to make your own

A subagent is a helper Claude starts to do one job in its own context window and report back a summary. Claude Code has built-in ones, such as Explore for searching code, and you can add your own as Markdown files in .claude/agents/ with their own instructions, tools and model. They keep long searches and logs out of your main conversation.

Extend

Take this page into your AI

ChatGPT Claude

A Subagent is a second Claude that your session starts to do one job. It gets a fresh Context Window, its own instructions and only the tools it is allowed. It works through the job, then returns a summary. Everything it read along the way stays in its context, not yours.

That is the point of them. Searching a large codebase, reading dozens of files or running a noisy test suite fills a conversation with text you will never look at again. Hand that to a subagent and your main conversation receives a paragraph instead.

The built-in subagents

Claude Code uses these on its own when a task fits:

Subagent	Can	Used for
Explore	Read only	Finding files and understanding code without changing anything
Plan	Read only	Gathering context in plan mode before Claude proposes a plan
general-purpose	Every tool	Jobs that need both looking around and making changes

Explore and Plan start without your CLAUDE.md, to keep them fast and cheap. You will see them in the transcript as a row with the subagent's name and a short task.

Make your own

The quickest way is to ask:

Create a project subagent in .claude/agents/ called test-runner. It runs
the test suite, reads the failures and reports which tests fail and why,
without changing any code. Give it Read, Grep, Glob and Bash, and use Sonnet.

Claude writes a file like this, which you can also write by hand:

---
name: test-runner
description: Runs the tests and explains failures. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You run this project's tests with `pnpm test` and report back.
For each failing test, give the file, the test name, the error in one
line and the most likely cause. Do not edit files. If everything passes,
say so in one line.

The text below the frontmatter is the subagent's whole system prompt: it replaces Claude Code's own instructions rather than adding to them, so say everything it needs. Save it in .claude/agents/ to share it with the project, or ~/.claude/agents/ to have it in all your projects.

Field	What it sets
`name`, `description`	Required. Claude chooses a subagent by its description; "use proactively" encourages it to delegate without being asked
`tools`	The tools it may use. Leave it out and it gets them all
`disallowedTools`	Tools to take away from what it would otherwise have
`model`	`haiku`, `sonnet`, `opus`, `fable`, a full id, or `inherit`
`permissionMode`	Its own permission mode, such as `plan`
`skills`	Skills loaded into it at the start
`mcpServers`	MCP servers only it can use
`isolation: worktree`	Runs it in its own Git worktree, so its edits cannot touch yours
`maxTurns`	Stops it after that many steps
`memory`	Lets it keep its own notes between sessions

A read-only subagent, with tools: Read, Grep, Glob, is a cheap way to be sure a review or a search never changes anything.

Calling a subagent

Ask in words: "use the test-runner subagent to check my changes". Claude usually delegates.
@-mention it: type @ and pick it from the list, to make sure that one runs.
Run the whole session as it: claude --agent test-runner, or set agent in settings.

Subagents usually run in the background while you keep working, and their result arrives as a message when they finish. Press Ctrl+B to move a running one to the background yourself, and run /tasks to see them. If one needs permission, the prompt appears in your session with its name.

Forks: a subagent that knows the conversation

A normal subagent starts knowing nothing but its task. A fork starts with a copy of your whole conversation, so it understands what you have been doing, then works on its own:

/subtask draft unit tests for the parser changes so far

It runs below your prompt while you carry on, and its result comes back as a message.

When not to use one

Stay in the main conversation when the task needs back and forth with you, when several steps share a lot of context, or for a small change. A subagent starts from nothing and has to find its way around, which takes time and tokens.

Every subagent sends its own requests, and they count against the same usage limits as your conversation. Up to 20 can run at once, and they can start their own subagents up to 3 layers deep, so the requests can multiply fast. Give simple jobs to haiku to keep the cost down.

Keep descriptions short too: all your subagents' descriptions are loaded into every session so Claude knows what is available, and Claude Code warns at startup when together they pass 15,000 tokens.

Questions

What is a subagent in Claude Code?: A separate Claude that your session starts for one task. It has its own context window, its own instructions and only the tools it is given. It works through the task, then hands back a short summary, so the files it read and the output it saw never fill your main conversation.
How do I create a custom subagent?: Ask Claude to write one, such as "create a read-only test-runner subagent in .claude/agents/ that uses Sonnet", or write the file yourself - a Markdown file with name, description and optional tools and model between --- lines, and the subagent's instructions below.
How do I make Claude use a particular subagent?: Name it in your message ("use the code-reviewer subagent on my changes"), or type @ and pick it so it is sure to run. To make a whole session run as that subagent, start with claude --agent code-reviewer.
Do subagents cost more?: Each subagent sends its own requests, which count against the same usage limits as your main conversation, and several running at once add up quickly. They can also save money when you give a simple job to a cheaper model such as Haiku, and they keep your main conversation smaller.
What is the difference between a subagent and a skill?: A skill is instructions that run in your current conversation. A subagent runs in its own separate context with its own tools and returns only its result. Use a skill for a procedure you want to watch, and a subagent for a self-contained job whose working steps you do not need.

Sources