Last updated: November 10, 2026
TL;DR
Use a Claude Code subagent when a side task would fill your conversation with search results, logs or file contents you won't need again. The subagent does that work in its own context window and returns a summary. To make your own, save a Markdown file with a name and a description in .claude/agents/, then limit its tools and model.
- 🧠 What a subagent is. A worker inside one session, with its own context, system prompt, tools and permissions.
- ⚖️ When to use one. Verbose output, tool limits or self-contained work. Back-and-forth stays in the main conversation.
- 📄 How to create one. One Markdown file with two required fields, in your project or your home folder.
- 🔒 How to limit one. Set its tools, its model and its permission mode in the same file.
- ▶️ How to run one. Claude delegates on its own, or you name the subagent or @-mention it.
- 📏 What it costs. Its requests count toward your usage limits, with 20 running at once and three layers of nesting by default.
Everything below comes from Anthropic's subagents docs, read on November 8, 2026, when Claude Code was at 2.1.319.
What Claude Code subagents are
A Claude Code subagent is a worker that runs inside one session, in its own context window, with its own system prompt, tool access and permissions. Claude hands it a task, it works independently, and only its result comes back, so the search results and logs it read stay out of your main conversation.
A subagent starts fresh. It doesn't see your conversation history, the files Claude already read or the skills you've already invoked. It gets its own system prompt, the task message Claude writes for it, your CLAUDE.md files, a snapshot of git status and any skills named in its file. If a rule from your conversation has to reach it, say so when you delegate.
Claude Code ships with built-in subagents, and Claude uses them when they fit:
| Built-in | Tools | Model | Used for |
|---|---|---|---|
| Explore | Read-only | The main conversation's model, with an exception when that's Fable | Finding files and searching code |
| Plan | Read-only | Inherits from the main conversation | Research while you're in plan mode |
| General-purpose | Every tool available to subagents | CLAUDE_CODE_SUBAGENT_MODEL if set, otherwise the main conversation's | Work that both reads and changes things |
Explore and Plan skip your CLAUDE.md files and the git status snapshot so research stays fast and cheap. They're also one-shot, so Claude can't resume them.
A fork is the exception to starting fresh. It's a subagent that inherits the whole conversation, so you can hand it a side task without explaining the background again, and only its result comes back. Start one with /subtask followed by the task. Because a fork reuses the main session's prompt cache, it costs less than a fresh subagent for a task that needs the same context.
When to use a subagent, and when not to
Use a subagent when a task produces verbose output you don't need in your main context, when you want to enforce tool restrictions, or when the work is self-contained and can return a summary. Stay in the main conversation for back-and-forth, for phases that share a lot of context and for quick changes.
| What you're doing | Use |
|---|---|
| Run the test suite and report only the failures | A subagent |
| Research three unrelated modules at once | Several subagents in parallel |
| Review code, then fix what the review found | Subagents chained in sequence |
| Iterate on a design with Claude | The main conversation |
| Make a quick, targeted change | The main conversation |
| Ask about something already in the conversation | /btw, which has no tool access and stays out of history |
| Reuse a prompt that should run in your main context | A skill |
| Independent tasks you hand off and check later | Agent view |
| One large change split across many pull requests | /batch |
Two costs come with delegating. A subagent that isn't a fork starts cold and may need time to gather context, so it's slower when latency matters. And every result returns to your main conversation, so many subagents that each send back a long report can use up the context you were trying to save. Ask for a short report:
Use a subagent to run the test suite and report only the failing tests with their error messages
Our guide to how to run Claude Code agents in parallel compares subagents with agent view, agent teams, dynamic workflows and projects.
How to create a custom subagent
A custom subagent is a Markdown file with YAML frontmatter, and only name and description are required. The quickest route is to ask Claude to write the file and then read what it wrote. Save it in .claude/agents/ for one project, or in ~/.claude/agents/ for every project on your machine.
Create a test-runner subagent in .claude/agents/ that runs the test suite and reports only failing tests. Make it read-only apart from running commands, and have it use Haiku.
The file looks like this. The body after the frontmatter is the subagent's system prompt:
---
name: test-runner
description: Runs the test suite and reports only failing tests with their error messages. Use after changing code.
tools: Read, Grep, Glob, Bash
model: haiku
---
Run the project's test suite. Report each failing test with its name, file and error message. Don't edit any files.
Anthropic's frontmatter reference lists 19 fields, and field names must match it exactly. Claude Code ignores a field it doesn't recognize and reports no error, so a misspelled disallowedtools does nothing and you won't be told.
Where you save the file decides who gets it. When two subagents share a name, the higher-priority location wins:
| Location | Who gets it | Priority |
|---|---|---|
| Managed settings | Your whole organization | 1 |
| Claude Code's agents flag at launch | The current session only | 2 |
.claude/agents/ | The current project, and your team if you commit it | 3 |
~/.claude/agents/ | All your projects | 4 |
A plugin's agents/ directory | Wherever the plugin is enabled | 5 |
The description is what Claude reads to decide when to delegate, so write it as a condition. Add "use proactively" to encourage delegation. Keep it short, because descriptions take up context, while the system prompt loads only when the subagent runs.
Older tutorials describe an interactive /agents wizard. That's how it worked through 2.1.197, and /agents now prints a reminder to ask Claude or edit those folders directly. If Claude can't find a new subagent, restart the session. That happens only when ~/.claude/agents/ didn't exist before the session started.
How to limit what a subagent can do
Limit a subagent with three frontmatter fields: tools for what it can call, model for what it runs on and permissionMode for what it may do without asking. Leave tools out and the subagent inherits every tool available to subagents, so a reviewer that should stay read-only needs an explicit list.
| Field | Example | What it does |
|---|---|---|
tools | Read, Grep, Glob | Allows only these tools |
disallowedTools | Write, Edit | Removes tools. An entry such as Bash(git push *) still removes the whole Bash tool |
model | haiku | Picks an alias (sonnet, opus, haiku, fable), a full model ID or inherit |
permissionMode | acceptEdits | Sets the permission mode, within the limits below |
maxTurns | 20 | Stops after that many turns and returns partial output Claude can resume |
isolation | worktree | Runs it in a temporary git worktree, cleaned up if it changes nothing |
omitClaudeMd | true | Starts it without your CLAUDE.md files |
effort | low | Overrides the session's effort level for this subagent |
Model order. Claude Code resolves a subagent's model in this order: the model Claude passes for that one call, the model field in the file, the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation's model. Before 2.1.251 the environment variable came first. Setting it alone doesn't change what Explore and Plan run on. Run /tasks to see the model on a subagent's row, which needs 2.1.242 or later.
Permission mode has limits. When your main conversation is in bypassPermissions, acceptEdits or auto mode, the subagent runs in that same mode and your permissionMode value is ignored. In plan mode it stays in plan mode. Your value applies when the main conversation is in default or dontAsk, and even then Claude Code won't let a subagent grant itself bypassPermissions.
Some tools never reach a subagent. AskUserQuestion and EnterPlanMode are removed for every subagent, and a background subagent keeps a shorter list of built-in tools.
How to run a subagent
Claude delegates on its own when a task matches a subagent's description, and you can step in by naming the subagent or @-mentioning it. Naming it in your prompt still leaves the decision to Claude, while an @-mention guarantees that subagent runs. Subagents Claude spawns from your main conversation start in the background by default.
Name it in plain language:
Have the test-runner subagent check my recent changes
Or pick it from the @ typeahead:
@"test-runner (agent)" check the auth changes
To run a whole session as a subagent, use Claude Code's agent flag at launch or set agent in .claude/settings.json. A custom subagent's system prompt then replaces the default Claude Code system prompt.
While a subagent runs in the background, you keep working. When it needs permission, the prompt appears in your main session and names the subagent. Press Esc to deny that one call without stopping it. A background subagent's result arrives in a later turn, and Claude waits for it before reporting.
If you need Claude to wait before it continues, set CLAUDE_CODE_FORK_SUBAGENT to 0 in the env block of your settings, start Claude Code again and ask it to wait for the report.
Each invocation is a new instance. To pick up where one left off, ask Claude to continue that work. A resumed subagent keeps its full history of tool calls and results.
What subagents cost and where they stop
Each subagent sends its own requests, and they count toward the same usage limits as your main conversation. Claude Code allows 20 running subagents in a session by default and three layers of nesting below the main conversation. Pointing high-volume work at a cheaper model such as Haiku is the direct way to spend less.
| Limit | Default | Change it with |
|---|---|---|
| Subagents running at once | 20 | CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS |
| Layers below the main conversation | 3 | CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, where 1 turns nesting off |
| Combined custom descriptions before a startup warning | 15,000 tokens | Trim the description fields; every subagent still loads |
| Total subagents over a session | No limit | – |
At 20 running, another spawn fails with Concurrent subagent limit reached and the error tells Claude not to retry. To keep one subagent from spawning its own, such as a reviewer that should stay read-only, leave Agent out of its tools list.
Frequently asked questions
What is a subagent in Claude Code?
A subagent is a worker Claude starts inside your session to handle one task in its own context window. It has its own system prompt, tools and permissions, and it returns only its result, so your main conversation doesn't fill up with the files and logs it read.
Does Claude Code support subagents?
Yes. Claude Code ships with built-in subagents, including Explore, Plan and general-purpose, and Claude uses them on its own in interactive sessions. You can add your own as Markdown files in .claude/agents/ or ~/.claude/agents/.
Are Claude Code subagents worth it?
They're worth it when a task produces a lot of output you won't reference again, or when you want hard tool limits. They cost extra usage and start without your conversation, so for back-and-forth or a quick change the main conversation is the better place.
What are the best subagents for Claude Code?
Start with the built-ins, since Claude already uses Explore and Plan for you. For custom ones, Anthropic's docs give four worked examples: a code reviewer, a debugger, a data scientist and a database query validator that blocks write operations. The test runner in this post is a small one to start with.
How many subagents can Claude Code run?
Claude Code allows 20 subagents running at once in a session by default, and CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes that. There's no limit on the total over a session. Subagents can nest three layers below the main conversation unless you set a different depth.
Where do Claude Code subagent files go?
Project subagents go in .claude/agents/ and personal ones in ~/.claude/agents/. Claude Code scans both recursively, so you can use subfolders, and each subagent's identity comes from its name field. Commit the project folder to share subagents with your team.
Do subagents use more of my usage limit?
Yes. Each subagent sends its own requests, and they count toward the same usage limits as your main conversation. Running several at once multiplies token use. Assign a cheaper model such as Haiku in the model field for high-volume work.
What's the difference between subagents and agent teams?
Subagents work inside one session and report to the session that started them. Agent teams are separate sessions that Claude spawns and supervises, and the workers can message each other under a lead. Use subagents for self-contained side tasks and agent teams when workers need to talk.
Give every subagent the same rules
Custom subagents load your CLAUDE.md files when they start, so the rules you've written down reach each one without a word from you. Explore, Plan and anything set with omitClaudeMd are the exceptions. Our guide to compound engineering for Claude Code shows how to build those rules up one fix at a time.
Stop guessing. Score your first workflow.
Score one workflow in about five minutes. Nine questions, a grade, and the specific gap holding it back - no call required.
Related Posts
Claude Code agent view: run and manage parallel sessions from one screen
How to use Claude Code agent view: open it with claude agents, dispatch one background session per task, read each row's state, peek and reply, attach for the full conversation, and clean up the worktrees afterward.
Claude Code /batch: split one large change across parallel agents
How Claude Code's /batch skill works and how to run it: prepare the repository, write the instruction, check the 5 to 30 unit plan, answer permission prompts, review one pull request per unit, and clean up the worktrees.
Best Claude connectors for small teams: what to turn on first (2026)
The Claude connectors a small team should turn on first, grouped by job: email, calendar and files, CRM, project management, design and development. What each can read and change, how to set every tool to Always allow, Needs approval or Blocked, and when to add custom connectors and desktop extensions.