Create custom subagents changedsub-agents
Nearest release: v2.1.304, published 6 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 20 Oct 2026 02:34 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+183added
Lines−195removed
From line
6
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits90to this page, all time
### Frontmatter reference #### Trust required for inline MCP servers ### Turn fork mode off
The whole hunk
from line 6, old and new numbered
/
from line 6
66
77Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. It also sends its own requests, which count toward the same [usage limits](/docs/en/costs#plan-usage-breakdown) as your main conversation. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results. To see the context savings in practice, the [context window visualization](/docs/en/context-window) walks through a session where a subagent handles research in its own separate window.
88
9<Note>
10 Subagents work within a single session. To run many independent sessions in parallel and monitor them from one place, see [background agents](/docs/en/agent-view). For separate sessions that pass messages to each other, see [cross-session messaging](/docs/en/cross-session-messaging). For a coordinated team of sessions Claude spawns and supervises, see [agent teams](/docs/en/agent-teams).
11</Note>
9> [!NOTE]
10>
11> Subagents work within a single session. To run many independent sessions in parallel and monitor them from one place, see [background agents](/docs/en/agent-view). For separate sessions that pass messages to each other, see [cross-session messaging](/docs/en/cross-session-messaging). For a coordinated team of sessions Claude spawns and supervises, see [agent teams](/docs/en/agent-teams).
1212
1313Subagents help you:
1414
from line 28
2828
2929Explore and Plan start without your CLAUDE.md files and the git status snapshot to keep research fast and inexpensive. Other built-in and [custom subagents](#configure-subagents) load both, unless you set [`omitClaudeMd`](#supported-frontmatter-fields) in a custom subagent's definition to start it without the user, project, and local CLAUDE.md files. For the full breakdown of what reaches a subagent, see [what loads at startup](#what-loads-at-startup).
3030
31<Tabs>
32 <Tab title="Explore">
33 A fast, read-only agent optimized for searching and analyzing codebases.
31**Explore**
3432
35 * **Model**: the main conversation's model. When the main conversation runs Fable, Explore's model depends on how you connect:
36 * With a Claude subscription, an Anthropic Console account, or an [LLM gateway](/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](/docs/en/model-config#model-aliases) resolves to.
37 * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](/docs/en/claude-platform-on-aws), or a [Claude apps gateway](/docs/en/claude-apps-gateway), Explore stays on the main conversation's model.
38 * **Tools**: read-only tools; Write and Edit are denied
39 * **Purpose**: file discovery, code search, codebase exploration
33A fast, read-only agent optimized for searching and analyzing codebases.
4034
41 A [user or project subagent](#choose-the-subagent-scope) named `Explore` overrides the built-in and keeps its own `model` field, so define one with `model: haiku` to run exploration on a lower-cost model. To force one model onto every subagent, Explore included, see [Run every subagent on one model](#run-every-subagent-on-one-model).
35* **Model**: the main conversation's model. When the main conversation runs Fable, Explore's model depends on how you connect:
36 * With a Claude subscription, an Anthropic Console account, or an [LLM gateway](/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](/docs/en/model-config#model-aliases) resolves to.
37 * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](/docs/en/claude-platform-on-aws), or a [Claude apps gateway](/docs/en/claude-apps-gateway), Explore stays on the main conversation's model.
38* **Tools**: read-only tools; Write and Edit are denied
39* **Purpose**: file discovery, code search, codebase exploration
4240
43 Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context.
41A [user or project subagent](#choose-the-subagent-scope) named `Explore` overrides the built-in and keeps its own `model` field, so define one with `model: haiku` to run exploration on a lower-cost model. To force one model onto every subagent, Explore included, see [Run every subagent on one model](#run-every-subagent-on-one-model).
4442
45 When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis.
46 </Tab>
43Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context.
4744
48 <Tab title="Plan">
49 A research agent used during [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.
45When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis.
5046
51 * **Model**: inherits from the main conversation, unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)
52 * **Tools**: read-only tools; Write and Edit are denied
53 * **Purpose**: codebase research for planning
47**Plan**
5448
55 When you're in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent so that exploration output stays in a separate context window while the main conversation remains read-only.
56 </Tab>
49A research agent used during [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.
5750
58 <Tab title="General-purpose">
59 A capable agent for complex, multi-step tasks that require both exploration and action.
51* **Model**: inherits from the main conversation, unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)
52* **Tools**: read-only tools; Write and Edit are denied
53* **Purpose**: codebase research for planning
6054
61 * **Model**: the [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) model if you set one and nothing assigns a model another way, otherwise the main conversation's model; [Choose a model](#choose-a-model) states the full order, and [Run every subagent on one model](#run-every-subagent-on-one-model) shows how to make the variable override those sources
62 * **Tools**: every tool [available to subagents](#available-tools)
63 * **Purpose**: complex research, multi-step operations, code modifications
55When you're in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent so that exploration output stays in a separate context window while the main conversation remains read-only.
6456
65 Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.
66 </Tab>
57**General-purpose**
6758
68 <Tab title="Other">
69 Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.
59A capable agent for complex, multi-step tasks that require both exploration and action.
7060
71 | Agent | Model | When Claude uses it |
72 | :- | :- | :- |
73 | claude | None of its own; follows the [model order](#choose-a-model) when Claude spawns it as a subagent | When a task doesn't fit a more specialized agent. A catch-all with every tool [available to subagents](#available-tools). Also the default agent for a dispatched [background session](/docs/en/agent-view); [which permission mode it starts in](/docs/en/agent-view#permission-mode-model-and-effort) depends on how the session was started |
74 | statusline-setup | Sonnet | When you run `/statusline` to configure your status line |
75 | claude-code-guide | Haiku | When you ask questions about Claude Code features |
76 </Tab>
77</Tabs>
61* **Model**: the [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) model if you set one and nothing assigns a model another way, otherwise the main conversation's model; [Choose a model](#choose-a-model) states the full order, and [Run every subagent on one model](#run-every-subagent-on-one-model) shows how to make the variable override those sources
62* **Tools**: every tool [available to subagents](#available-tools)
63* **Purpose**: complex research, multi-step operations, code modifications
7864
65Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.
66
67**Other**
68
69Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.
70
71| Agent | Model | When Claude uses it |
72| :- | :- | :- |
73| claude | None of its own; follows the [model order](#choose-a-model) when Claude spawns it as a subagent | When a task doesn't fit a more specialized agent. A catch-all with every tool [available to subagents](#available-tools). Also the default agent for a dispatched [background session](/docs/en/agent-view); [which permission mode it starts in](/docs/en/agent-view#permission-mode-model-and-effort) depends on how the session was started |
74| statusline-setup | Sonnet | When you run `/statusline` to configure your status line |
75| claude-code-guide | Haiku | When you ask questions about Claude Code features |
76
7977Built-in subagents are registered by default in interactive sessions. To restrict them:
8078
8179* To block a specific built-in type, add it to `permissions.deny` as shown in [Disable specific subagents](#disable-specific-subagents).
from line 91
9391
9492This walkthrough creates a user-level subagent that reviews code and suggests improvements.
9593
96<Steps>
97 <Step title="Ask Claude to create the subagent">
98 In Claude Code, describe the subagent you want and where to save it:
94**1. Ask Claude to create the subagent**
9995
100 ```text wrap theme={null}
101 Create a personal code-improver subagent in ~/.claude/agents/ that scans
102 files and suggests improvements for readability, performance, and best
103 practices. It should explain each issue, show the current code, and
104 provide an improved version. Make it read-only and have it use Sonnet.
105 ```
96In Claude Code, describe the subagent you want and where to save it:
10697
107 Claude writes the file with a `name`, a `description`, a `tools` list, a `model`, and a system prompt.
108 </Step>
98```text wrap theme={null}
99Create a personal code-improver subagent in ~/.claude/agents/ that scans
100files and suggests improvements for readability, performance, and best
101practices. It should explain each issue, show the current code, and
102provide an improved version. Make it read-only and have it use Sonnet.
103```
109104
110 <Step title="Review the file">
111 Open `~/.claude/agents/code-improver.md` and confirm the frontmatter matches what you asked for. The result looks like this:
105Claude writes the file with a `name`, a `description`, a `tools` list, a `model`, and a system prompt.
112106
113 ```markdown theme={null}
114 ---
115 name: code-improver
116 description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
117 tools: Read, Grep, Glob
118 model: sonnet
119 ---
107**2. Review the file**
120108
121 You are a code improvement specialist. For each issue you find, explain
122 the problem, show the current code, and provide an improved version.
123 ```
109Open `~/.claude/agents/code-improver.md` and confirm the frontmatter matches what you asked for. The result looks like this:
124110
125 Because the file lives in `~/.claude/agents/`, the subagent is available in every project on your machine. To scope it to one project instead, move it to that project's `.claude/agents/` directory. [Choose the subagent scope](#choose-the-subagent-scope) compares the two.
126 </Step>
111```markdown theme={null}
112---
113name: code-improver
114description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
115tools: Read, Grep, Glob
116model: sonnet
117---
127118
128 <Step title="Try it out">
129 Ask Claude to delegate to the new subagent:
119You are a code improvement specialist. For each issue you find, explain
120the problem, show the current code, and provide an improved version.
121```
130122
131 ```text wrap theme={null}
132 Use the code-improver agent to suggest improvements in this project
133 ```
123Because the file lives in `~/.claude/agents/`, the subagent is available in every project on your machine. To scope it to one project instead, move it to that project's `.claude/agents/` directory. [Choose the subagent scope](#choose-the-subagent-scope) compares the two.
134124
135 Claude delegates to your new subagent, which scans the codebase and returns improvement suggestions. In the transcript, the delegation appears as a tool call row showing the subagent's name followed by a short task description, such as `code-improver(Suggest code improvements)`.
125**3. Try it out**
136126
137 If Claude can't find the new subagent, restart Claude Code and try again. This happens only when `~/.claude/agents/` didn't exist before the session started, because a running session doesn't detect a newly created `agents` directory.
138 </Step>
139</Steps>
127Ask Claude to delegate to the new subagent:
140128
129```text wrap theme={null}
130Use the code-improver agent to suggest improvements in this project
131```
132
133Claude delegates to your new subagent, which scans the codebase and returns improvement suggestions. In the transcript, the delegation appears as a tool call row showing the subagent's name followed by a short task description, such as `code-improver(Suggest code improvements)`.
134
135If Claude can't find the new subagent, restart Claude Code and try again. This happens only when `~/.claude/agents/` didn't exist before the session started, because a running session doesn't detect a newly created `agents` directory.
136
141137You now have a subagent you can use in any project on your machine to analyze codebases and suggest improvements.
142138
143139You can also write subagent files by hand, define them via CLI flags, or distribute them through plugins. The following sections cover all configuration options.
144140
145<Note>
146 Running `/agents` prints a reminder to ask Claude or edit `.claude/agents/` and `~/.claude/agents/` directly.
147 On Claude Code v2.1.197 and earlier, `/agents` opens an interactive wizard with a **Running** tab that lists live subagents and a **Library** tab for creating, editing, and deleting them. 
148</Note>
141> [!NOTE]
142>
143> Running `/agents` prints a reminder to ask Claude or edit `.claude/agents/` and `~/.claude/agents/` directly.
144> On Claude Code v2.1.197 and earlier, `/agents` opens an interactive wizard with a **Running** tab that lists live subagents and a **Library** tab for creating, editing, and deleting them. 
149145
150146## Configure subagents
151147
from line 175
179175
180176**CLI-defined subagents** are passed as JSON when launching Claude Code. They exist only for that session and aren't saved to disk, making them useful for quick testing or automation scripts. You can define multiple subagents in a single `--agents` call:
181177
182<Tabs>
183 <Tab title="macOS, Linux, WSL">
184 ```bash theme={null}
185 claude --agents '{
186 "code-reviewer": {
187 "description": "Expert code reviewer. Use proactively after code changes.",
188 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
189 "tools": ["Read", "Grep", "Glob", "Bash"],
190 "model": "sonnet"
191 },
192 "debugger": {
193 "description": "Debugging specialist for errors and test failures.",
194 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
195 }
196 }'
197 ```
198 </Tab>
178**macOS, Linux, WSL**
199179
200 <Tab title="Windows PowerShell">
201 ```powershell theme={null}
202 claude --agents @'
203 {
204 "code-reviewer": {
205 "description": "Expert code reviewer. Use proactively after code changes.",
206 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
207 "tools": ["Read", "Grep", "Glob", "Bash"],
208 "model": "sonnet"
209 },
210 "debugger": {
211 "description": "Debugging specialist for errors and test failures.",
212 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
213 }
214 }
215 '@
216 ```
217 </Tab>
218</Tabs>
180```bash theme={null}
181claude --agents '{
182 "code-reviewer": {
183 "description": "Expert code reviewer. Use proactively after code changes.",
184 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
185 "tools": ["Read", "Grep", "Glob", "Bash"],
186 "model": "sonnet"
187 },
188 "debugger": {
189 "description": "Debugging specialist for errors and test failures.",
190 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
191 }
192}'
193```
219194
195**Windows PowerShell**
196
197```powershell theme={null}
198claude --agents @'
199{
200 "code-reviewer": {
201 "description": "Expert code reviewer. Use proactively after code changes.",
202 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
203 "tools": ["Read", "Grep", "Glob", "Bash"],
204 "model": "sonnet"
205 },
206 "debugger": {
207 "description": "Debugging specialist for errors and test failures.",
208 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
209 }
210}
211'@
212```
213
220214In [non-interactive mode](/docs/en/headless), `--agents` also accepts the path to a JSON file holding the same object, for definitions too large to pass on the command line. For example, `claude -p --agents ./agents.json "Review my changes"` reads the definitions from that file. In an interactive session, Claude Code refuses a file path. The file form requires Claude Code v2.1.281 or later.
221215
222216Each top-level key in the JSON is an agent's name, and its value is that agent's definition. Don't start a name with `-`. A definition takes these fields:
from line 225
231225
232226**Plugin subagents** come from [plugins](/docs/en/plugins/overview) you've installed. They load automatically alongside your custom subagents and appear in the @-mention typeahead under their scoped name. See the [plugin components reference](/docs/en/plugins/components#agents) for details on creating plugin subagents.
233227
234<Note>
235 For security reasons, plugin subagents don't support the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields. These fields are ignored when loading agents from a plugin. If you need them, copy the agent file into `.claude/agents/` or `~/.claude/agents/`. You can also add rules to [`permissions.allow`](/docs/en/settings-reference#permissions-allow) in `settings.json` or `settings.local.json`, but these rules apply to the entire session, not only the plugin subagent.
228> [!NOTE]
229>
230> For security reasons, plugin subagents don't support the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields. These fields are ignored when loading agents from a plugin. If you need them, copy the agent file into `.claude/agents/` or `~/.claude/agents/`. You can also add rules to [`permissions.allow`](/docs/en/settings-reference#permissions-allow) in `settings.json` or `settings.local.json`, but these rules apply to the entire session, not only the plugin subagent.
231>
232> If you're the plugin's author, ship the hooks in the plugin's [`hooks/hooks.json`](/docs/en/plugins/components#hooks) and the MCP servers in its [`.mcp.json`](/docs/en/plugins/components#mcp-servers) instead. They apply whenever the plugin is enabled rather than only inside the subagent.
236233
237 If you're the plugin's author, ship the hooks in the plugin's [`hooks/hooks.json`](/docs/en/plugins/components#hooks) and the MCP servers in its [`.mcp.json`](/docs/en/plugins/components#mcp-servers) instead. They apply whenever the plugin is enabled rather than only inside the subagent.
238</Note>
239
240234You can also reuse a subagent definition as an [agent team](/docs/en/agent-teams) teammate: name the subagent type when you ask Claude to spawn the teammate, and Claude Code applies parts of that definition to it. [Use subagent definitions for teammates](/docs/en/agent-teams#use-subagent-definitions-for-teammates) says which scopes and which parts apply in each display mode.
241235
242236### Write subagent files
from line 237
243237
244238Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:
245239
246<Note>
247 Claude Code watches `~/.claude/agents/` and `.claude/agents/`. When you add or edit a subagent file on disk, or ask Claude to write one for you, Claude Code detects the change within a few seconds and the next delegation uses the updated definition, with no restart needed.
240> [!NOTE]
241>
242> Claude Code watches `~/.claude/agents/` and `.claude/agents/`. When you add or edit a subagent file on disk, or ask Claude to write one for you, Claude Code detects the change within a few seconds and the next delegation uses the updated definition, with no restart needed.
243>
244> Three cases still need a restart:
245>
246> * The watcher covers only directories that existed when the session started, so after creating a scope's first agent file in a new `agents` directory, restart to load it.
247> * Claude Code doesn't watch `.claude/agents/` inside directories added with `--add-dir` or `/add-dir`, so after adding or editing a subagent there, restart to load the change.
248> * Sessions started with `--disable-slash-commands` don't watch these directories at all.
248249
249 Three cases still need a restart:
250
251 * The watcher covers only directories that existed when the session started, so after creating a scope's first agent file in a new `agents` directory, restart to load it.
252 * Claude Code doesn't watch `.claude/agents/` inside directories added with `--add-dir` or `/add-dir`, so after adding or editing a subagent there, restart to load the change.
253 * Sessions started with `--disable-slash-commands` don't watch these directories at all.
254</Note>
255
256250```markdown .claude/agents/code-reviewer.md theme={null}
257251---
258252name: code-reviewer
from line 280
286280
287281When the main conversation itself runs isolated in a worktree, Claude Code applies the same checks to the session and to every subagent it spawns, including subagents without `isolation: worktree`; see [How Claude Code enforces isolation](/docs/en/worktrees#how-claude-code-enforces-isolation).
288282
289<h3 id="supported-frontmatter-fields">
290 Frontmatter reference
291</h3>
283### Frontmatter reference
292284
293285Configure a subagent with YAML [frontmatter](/docs/en/glossary#frontmatter) between `---` markers at the top of its file, and write its system prompt as Markdown after the closing `---`. Only `name` and `description` are required.
294286
from line 489
497489
498490When an agent runs as the main thread with `claude --agent`, it can spawn subagents using the Agent tool. To restrict which subagent types it can spawn, use `Agent(agent_type)` syntax in the `tools` field.
499491
500<Note>In version 2.1.63, the Task tool was renamed to Agent. Existing `Task(...)` references in settings and agent definitions still work as aliases.</Note>
492> [!NOTE]
493>
494> In version 2.1.63, the Task tool was renamed to Agent. Existing `Task(...)` references in settings and agent definitions still work as aliases.
501495
502496```yaml theme={null}
503497---
from line 517
523517
524518Use the `mcpServers` field to give a subagent access to [MCP](/docs/en/mcp) servers that aren't available in the main conversation. Inline servers defined here are connected when the subagent starts, subject to the [trust rule for the agent file's folder](#inline-server-trust), and disconnected when it finishes. String references share the parent session's connection.
525519
526<Note>
527 The `mcpServers` field applies in both contexts where an agent file can run:
520> [!NOTE]
521>
522> The `mcpServers` field applies in both contexts where an agent file can run:
523>
524> * As a subagent, spawned through the Agent tool or an @-mention
525> * As the main session, launched with [`--agent`](#invoke-subagents-explicitly) or the `agent` setting
526>
527> When the agent is the main session, inline server definitions connect at startup alongside servers from [`.mcp.json`](/docs/en/mcp) and settings files, under the same [trust rule for the agent file's folder](#inline-server-trust). In `/mcp`, a remote (HTTP or SSE) server you've used before can show the [`cached` status](/docs/en/mcp#managing-your-servers) instead; Claude Code connects it when Claude first calls one of its tools.
528528
529 * As a subagent, spawned through the Agent tool or an @-mention
530 * As the main session, launched with [`--agent`](#invoke-subagents-explicitly) or the `agent` setting
531
532 When the agent is the main session, inline server definitions connect at startup alongside servers from [`.mcp.json`](/docs/en/mcp) and settings files, under the same [trust rule for the agent file's folder](#inline-server-trust). In `/mcp`, a remote (HTTP or SSE) server you've used before can show the [`cached` status](/docs/en/mcp#managing-your-servers) instead; Claude Code connects it when Claude first calls one of its tools.
533</Note>
534
535529Each entry in the list is either an inline server definition or a string referencing an MCP server already configured in your session:
536530
537531```yaml theme={null}
from line 559
565559
566560Managed-settings restrictions apply to every subagent regardless of how it is defined. `--strict-mcp-config` doesn't filter servers you pass inline via `--agents` or the SDK `agents` option, since those are explicit caller input.
567561
568<h4 id="inline-server-trust">
569 Trust required for inline MCP servers
570</h4>
562#### Trust required for inline MCP servers
571563
572564Claude Code loads an [inline MCP server](#scope-mcp-servers-to-a-subagent) from an agent file in your project's `.claude/agents/` directory, or in an `--add-dir` directory's `.claude/agents/`, only after you [trust the folder the agent file came from](/docs/en/permissions#what-runs-before-you-trust-a-folder). Before v2.1.238, Claude Code loaded these servers without checking trust.
573565
from line 616
624616
625617If a listed skill is missing or disabled, for example by your organization's policy, Claude Code skips it and logs a warning to the debug log.
626618
627<Note>
628 This is the inverse of [running a skill in a subagent](/docs/en/skills#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. In both cases the subagent starts without your conversation history.
629</Note>
619> [!NOTE]
620>
621> This is the inverse of [running a skill in a subagent](/docs/en/skills#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. In both cases the subagent starts without your conversation history.
630622
631623#### Enable persistent memory
632624
from line 746
754746
755747Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes.
756748
757<Note>
758 Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention, and when the agent runs as the main session via [`--agent`](#invoke-subagents-explicitly) or the `agent` setting. In the main-session case they run alongside any hooks defined in [`settings.json`](/docs/en/hooks).
759</Note>
749> [!NOTE]
750>
751> Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention, and when the agent runs as the main session via [`--agent`](#invoke-subagents-explicitly) or the `agent` setting. In the main-session case they run alongside any hooks defined in [`settings.json`](/docs/en/hooks).
760752
761753To let a project-level subagent's frontmatter hooks run, accept the [workspace trust dialog](/docs/en/permissions#project-allow-rules-and-workspace-trust) for the folder that contains the agent file. Hooks from user-level subagents in `~/.claude/agents/` and from definitions you pass with `--agents` run without this step. If you added a folder with `--add-dir` from outside your trusted workspace's repository, trust that folder separately: its `.claude/agents/` hooks don't inherit the workspace's grant.
762754
from line 1001
10091001
10101002Each subagent explores its area independently, then Claude synthesizes the findings. This works best when the research paths don't depend on each other.
10111003
1012<Warning>
1013 When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context, and each subagent spends tokens of its own while it runs.
1014</Warning>
1004> [!WARNING]
1005>
1006> When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context, and each subagent spends tokens of its own while it runs.
10151007
10161008For work that needs to keep running in parallel or won't fit in one context window, run it in [separate sessions](/docs/en/agents) and let Claude [pass findings between them](/docs/en/cross-session-messaging).
10171009
from line 1059
10671059
10681060In the terminal, Claude Code shows nested subagents as a tree in the subagent panel below the prompt input and marks each row that still has descendants in the panel with a `(+N)` count of them. Open a row to see that subagent's siblings and direct children with a path back to `main`.
10691061
1070<Note>
1071 Earlier versions used different defaults:
1062> [!NOTE]
1063>
1064> Earlier versions used different defaults:
1065>
1066> * **v2.1.172 through v2.1.216**: subagents could nest by default, up to five layers deep, and the limit couldn't be changed.
1067> * **v2.1.217 through v2.1.218**: the limit defaulted to one, so a subagent couldn't spawn its own unless you raised it; v2.1.219 raised the default to three.
10721068
1073 * **v2.1.172 through v2.1.216**: subagents could nest by default, up to five layers deep, and the limit couldn't be changed.
1074 * **v2.1.217 through v2.1.218**: the limit defaulted to one, so a subagent couldn't spawn its own unless you raised it; v2.1.219 raised the default to three.
1075</Note>
1076
10771069### Concurrent subagent limit
10781070
10791071Two limits control subagent use, each with its own variable: this one stops Claude from spawning more subagents while too many are running, and the [depth limit](#let-subagents-spawn-their-own-subagents) caps how deeply subagents nest. There's no limit on the total number of subagents Claude can spawn over a session.
from line 1169
11771169
11781170The `preTokens` value shows how many tokens were used before compaction occurred.
11791171
1180<a id="subagent-auto-compact-window" />
1181
11821172##### Set the auto-compact window for one subagent
11831173
11841174To make one subagent compact earlier than it otherwise would, set `autoCompactWindow` in its [frontmatter](#supported-frontmatter-fields) to a token count from `100000` to `1000000`. If you set [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/en/env-vars#variables), the subagent uses that variable's window instead and the field has no effect, unless Claude Code [ignores the variable's value](/docs/en/model-config#claude_code_auto_compact_window-values). Requires Claude Code v2.1.296 or later.
from line 1192
12021192
12031193## Fork the current conversation
12041194
1205<Note>
1206 When [agent view is turned off](/docs/en/agent-view#turn-off-agent-view), `/subtask` isn't available and `/fork` starts the forked subagent instead; otherwise `/fork` copies the whole session into a new [background session](/docs/en/agent-view#from-inside-a-session).
1207</Note>
1195> [!NOTE]
1196>
1197> When [agent view is turned off](/docs/en/agent-view#turn-off-agent-view), `/subtask` isn't available and `/fork` starts the forked subagent instead; otherwise `/fork` copies the whole session into a new [background session](/docs/en/agent-view#from-inside-a-session).
12081198
12091199A fork is a subagent that inherits the entire conversation so far instead of starting fresh. This drops the input isolation that subagents otherwise provide: a fork sees the same system prompt, tools, model, and message history as the main session, so you can hand it a side task without re-explaining the situation. The fork's own tool calls still stay out of your conversation and only its final result comes back, so your main context window stays clean. Use a fork when any other subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point.
12101200
from line 1245
12551245
12561246When Claude spawns a fork through the Agent tool, it can pass `isolation: "worktree"` so the fork's file edits are written to a separate git worktree instead of your checkout. A fork can't spawn further forks.
12571247
1258<h3 id="turn-fork-mode-on-or-off">
1259 Turn fork mode off
1260</h3>
1248### Turn fork mode off
12611249
12621250Fork mode lets Claude start a fork on its own. To stop Claude from starting forks:
12631251
from line 1258
12701258
12711259These examples demonstrate effective patterns for building subagents. Use them as starting points, or generate a customized version with Claude.
12721260
1273<Tip>
1274 **Best practices:**
1275
1276 * **Design focused subagents:** each subagent should excel at one specific task
1277 * **Write descriptions that single out one subagent:** Claude uses the description to decide when to delegate. Make each description specific enough to route to the right subagent, and keep the combined set within the [15,000-token description budget](#understand-automatic-delegation)
1278 * **Limit tool access:** grant only necessary permissions for security and focus
1279 * **Check into version control:** share project subagents with your team
1280</Tip>
1261> [!TIP]
1262>
1263> **Best practices:**
1264>
1265> * **Design focused subagents:** each subagent should excel at one specific task
1266> * **Write descriptions that single out one subagent:** Claude uses the description to decide when to delegate. Make each description specific enough to route to the right subagent, and keep the combined set within the [15,000-token description budget](#understand-automatic-delegation)
1267> * **Limit tool access:** grant only necessary permissions for security and focus
1268> * **Check into version control:** share project subagents with your team
12811269
12821270### Code reviewer
12831271
No line in this hunk matches that.