65 Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.65 Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.
66 66
67 | Agent | Model | When Claude uses it |67 | Agent | Model | When Claude uses it |
68 | :---------------- | :------- | :------------------------------------------------------- |68 | :---------------- | :----- | :------------------------------------------------------- |
69 | Bash | Inherits | Running terminal commands in a separate context |
70 | statusline-setup | Sonnet | When you run `/statusline` to configure your status line |69 | statusline-setup | Sonnet | When you run `/statusline` to configure your status line |
71 | Claude Code Guide | Haiku | When you ask questions about Claude Code features |70 | Claude Code Guide | Haiku | When you ask questions about Claude Code features |
72 </Tab>71 </Tab>
157Subagents are Markdown files with YAML frontmatter. Store them in different locations depending on scope. When multiple subagents share the same name, the higher-priority location wins.156Subagents are Markdown files with YAML frontmatter. Store them in different locations depending on scope. When multiple subagents share the same name, the higher-priority location wins.
158 157
159| Location | Scope | Priority | How to create |158| Location | Scope | Priority | How to create |
160| :--------------------------- | :---------------------- | :---------- | :------------------------------------ |159| :--------------------------- | :---------------------- | :---------- | :-------------------------------------------- |
161| `--agents` CLI flag | Current session | 1 (highest) | Pass JSON when launching Claude Code |160| Managed settings | Organization-wide | 1 (highest) | Deployed via [managed settings](/en/settings) |
162| `.claude/agents/` | Current project | 2 | Interactive or manual |161| `--agents` CLI flag | Current session | 2 | Pass JSON when launching Claude Code |
163| `~/.claude/agents/` | All your projects | 3 | Interactive or manual |162| `.claude/agents/` | Current project | 3 | Interactive or manual |
164| Plugin's `agents/` directory | Where plugin is enabled | 4 (lowest) | Installed with [plugins](/en/plugins) |163| `~/.claude/agents/` | All your projects | 4 | Interactive or manual |
164| Plugin's `agents/` directory | Where plugin is enabled | 5 (lowest) | Installed with [plugins](/en/plugins) |
165 165
166**Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively.166**Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively.
167 167
186}'186}'
187```187```
188 188
189The `--agents` flag accepts JSON with the same [frontmatter](#supported-frontmatter-fields) fields as file-based subagents: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, and `isolation`. Use `prompt` for the system prompt, equivalent to the markdown body in file-based subagents.189The `--agents` flag accepts JSON with the same [frontmatter](#supported-frontmatter-fields) fields as file-based subagents: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation`, and `color`. Use `prompt` for the system prompt, equivalent to the markdown body in file-based subagents.
190
191**Managed subagents** are deployed by organization administrators. Place markdown files in `.claude/agents/` inside the [managed settings directory](/en/settings#settings-files), using the same frontmatter format as project and user subagents. Managed definitions take precedence over project and user subagents with the same name.
190 192
191**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.193**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.
192 194
223The following fields can be used in the YAML frontmatter. Only `name` and `description` are required.225The following fields can be used in the YAML frontmatter. Only `name` and `description` are required.
224 226
225| Field | Required | Description |227| Field | Required | Description |
226| :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |228| :---------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
227| `name` | Yes | Unique identifier using lowercase letters and hyphens |229| `name` | Yes | Unique identifier using lowercase letters and hyphens |
228| `description` | Yes | When Claude should delegate to this subagent |230| `description` | Yes | When Claude should delegate to this subagent |
229| `tools` | No | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted |231| `tools` | No | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted |
230| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |232| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |
231| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, a full model ID (for example, `claude-opus-4-6`), or `inherit`. Defaults to `inherit` |233| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, a full model ID (for example, `claude-opus-4-6`), or `inherit`. Defaults to `inherit` |
232| `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` |234| `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan` |
233| `maxTurns` | No | Maximum number of agentic turns before the subagent stops |235| `maxTurns` | No | Maximum number of agentic turns before the subagent stops |
234| `skills` | No | [Skills](/en/skills) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation |236| `skills` | No | [Skills](/en/skills) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation |
235| `mcpServers` | No | [MCP servers](/en/mcp) available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., `"slack"`) or an inline definition with the server name as key and a full [MCP server config](/en/mcp#configure-mcp-servers) as value |237| `mcpServers` | No | [MCP servers](/en/mcp) available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., `"slack"`) or an inline definition with the server name as key and a full [MCP server config](/en/mcp#installing-mcp-servers) as value |
236| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent |238| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent |
237| `memory` | No | [Persistent memory scope](#enable-persistent-memory): `user`, `project`, or `local`. Enables cross-session learning |239| `memory` | No | [Persistent memory scope](#enable-persistent-memory): `user`, `project`, or `local`. Enables cross-session learning |
238| `background` | No | Set to `true` to always run this subagent as a [background task](#run-subagents-in-foreground-or-background). Default: `false` |240| `background` | No | Set to `true` to always run this subagent as a [background task](#run-subagents-in-foreground-or-background). Default: `false` |
239| `effort` | No | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only) |241| `effort` | No | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only) |
240| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), giving it an isolated copy of the repository. The worktree is automatically cleaned up if the subagent makes no changes |242| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), giving it an isolated copy of the repository. The worktree is automatically cleaned up if the subagent makes no changes |
243| `color` | No | Display color for the subagent in the task list and transcript. Accepts `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan` |
241| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](/en/commands) and [skills](/en/skills) are processed. Prepended to any user-provided prompt |244| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](/en/commands) and [skills](/en/skills) are processed. Prepended to any user-provided prompt |
242 245
243### Choose a model246### Choose a model
342The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation and can override the mode, except when the parent mode takes precedence as described below.345The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation and can override the mode, except when the parent mode takes precedence as described below.
343 346
344| Mode | Behavior |347| Mode | Behavior |
345| :------------------ | :----------------------------------------------------------------- |348| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ |
346| `default` | Standard permission checking with prompts |349| `default` | Standard permission checking with prompts |
347| `acceptEdits` | Auto-accept file edits |350| `acceptEdits` | Auto-accept file edits except in protected directories |
351| `auto` | [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode): a background classifier reviews commands and protected-directory writes |
348| `dontAsk` | Auto-deny permission prompts (explicitly allowed tools still work) |352| `dontAsk` | Auto-deny permission prompts (explicitly allowed tools still work) |
349| `bypassPermissions` | Skip permission prompts |353| `bypassPermissions` | Skip permission prompts |
350| `plan` | Plan mode (read-only exploration) |354| `plan` | Plan mode (read-only exploration) |
351 355
352<Warning>356<Warning>
353 Use `bypassPermissions` with caution. It skips permission prompts, allowing the subagent to execute operations without approval. Writes to `.git`, `.claude`, `.vscode`, and `.idea` directories still prompt for confirmation, except for `.claude/commands`, `.claude/agents`, and `.claude/skills`. See [permission modes](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for details.357 Use `bypassPermissions` with caution. It skips permission prompts, allowing the subagent to execute operations without approval. Writes to `.git`, `.claude`, `.vscode`, `.idea`, and `.husky` directories still prompt for confirmation, except for `.claude/commands`, `.claude/agents`, and `.claude/skills`. See [permission modes](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for details.
354</Warning>358</Warning>
355 359
356If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden. If the parent uses [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode), the subagent inherits auto mode and any `permissionMode` in its frontmatter is ignored: the classifier evaluates the subagent's tool calls with the same block and allow rules as the parent session.360If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden. If the parent uses [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode), the subagent inherits auto mode and any `permissionMode` in its frontmatter is ignored: the classifier evaluates the subagent's tool calls with the same block and allow rules as the parent session.
690 694
691Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh.695Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh.
692 696
693When a subagent completes, Claude receives its agent ID. Claude uses the `SendMessage` tool with the agent's ID as the `to` field to resume it. The `SendMessage` tool is only available when [agent teams](/en/agent-teams) are enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` or the `--agent-teams` flag.697When a subagent completes, Claude receives its agent ID. Claude uses the `SendMessage` tool with the agent's ID as the `to` field to resume it. The `SendMessage` tool is only available when [agent teams](/en/agent-teams) are enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
694 698
695To resume a subagent, ask Claude to continue the previous work:699To resume a subagent, ask Claude to continue the previous work:
696 700
