Subagents
A subagent is a separate Claude run with its own context window, prompt, tools, and model.
It does a side task, such as a long search. It returns only a short summary, so your main conversation stays clean.
For example, Claude can send a code search to the Explore subagent and get back only the answer.
Example
An agent file for a read-only code reviewer.
---
name: reviewer
description: Reviews code for bugs and style problems. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
maxTurns: 20
---
You are a careful code reviewer.
Read the changed files and report bugs, with file and line.
Do not edit files.
Claude can now send review work to reviewer. You can also write @reviewer check the last commit.
Overview
| Item | Status | What it does | Notes |
|---|---|---|---|
| Agent file | Documented: An official docs page names this item. | A Markdown file with YAML frontmatter and a prompt body. | The body is the system prompt. Keys are on Subagent Frontmatter. |
Agent tool | Documented: An official docs page names this item. | Starts a subagent, a fork, or a teammate. | The tool lives in the main session and in subagents. |
-- flag and agent setting | Documented: An official docs page names this item. | Runs an agent as the main session. | initial applies. Agent(type) in tools limits which types it can start. |
@ mention | Documented: An official docs page names this item. | Invokes a subagent by name. | Interactive only. The docs explain this under explicit invocation. |
permissions. with Agent(name) | Documented: An official docs page names this item. | Disables one agent type. | Agent(fork) blocks forks. Deny Agent to stop all delegation. Task(... is an alias. |
Task alias | Documented: An official docs page names this item. | The old name of Agent (before 2.1.63). | Works in rules and agent files. |
/ | Documented: An official docs page names this item. | Starts a fork by hand (2.1.212). | On 2.1.161 to 2.1.211 the command was /. |
| Description cost | Documented: An official docs page names this item. | Subagent descriptions count toward context. | At startup the interactive screen warns Agent descriptions are over the 15,000-. It warns when the name: text of all non-built-in agents is over 15,000 tokens. Source: the program (not shown in -). |
Agent Locations and Priority
If the same name appears in two places, the higher priority wins.
| Priority | Place | Status | Notes |
|---|---|---|---|
| 1 (highest) | Managed settings | Documented: An official docs page names this item. | Pushed by an administrator. |
| 2 | -- JSON | Documented: An official docs page names this item. | This session only. Not saved. |
| 3 | . | Documented: An official docs page names this item. | Claude Code searches upward from the working folder. The closest definition wins. -- folders also load. |
| 4 | ~/. | Documented: An official docs page names this item. | Claude Code scans deep into subfolders. The name is the identity, not the path. |
| 5 (lowest) | Plugin agents/ | Documented: An official docs page names this item. | Subfolders become part of plugin:. |
How It Works
The subagent loads its own prompt, the task message, and the project CLAUDE.md files.
It returns a summary. The main conversation never sees the subagent's own steps.
See Subagent Runtime for the details, and Agent Loop for the loop it runs.
Pages in This Section
| Page | Content |
|---|---|
| Subagent Frontmatter | Every key of an agent file and of -- JSON. |
| Subagent Runtime | Built-in agents, tool filters, forks, background runs, depth limits, and teams. |
Related Pages
- Hooks:
SubagentStart,SubagentStop, and task events. - Skills and Commands: skills can run in a fork or be preloaded.
- Environment Variables for Agents and Teams: the full list of variables.
Source: Create Custom Subagents, Environment Variables, and the program.