Create custom subagents changedsub-agents
Upstream edited this page at 28 Oct 2026 19:31 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 30 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+80added
Lines−80removed
From line
28
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits101to this page, all time
The whole hunk
from line 28, old and new numbered
/
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**Explore**
31> [tab] Explore
32>
33> A fast, read-only agent optimized for searching and analyzing codebases.
34>
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](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](https://code.claude.com/docs/en/model-config#model-aliases) resolves to.
37> * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), or a [Claude apps gateway](https://code.claude.com/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
40>
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).
42>
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.
44>
45> When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis.
3246
33A fast, read-only agent optimized for searching and analyzing codebases.
47> [tab] Plan
48>
49> A research agent used during [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.
50>
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
54>
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.
3456
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](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](https://code.claude.com/docs/en/model-config#model-aliases) resolves to.
37 * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), or a [Claude apps gateway](https://code.claude.com/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
57> [tab] General-purpose
58>
59> A capable agent for complex, multi-step tasks that require both exploration and action.
60>
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
64>
65> Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.
4066
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).
67> [tab] Other
68>
69> Claude 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](https://code.claude.com/docs/en/agent-view.md); [which permission mode it starts in](https://code.claude.com/docs/en/agent-view.md#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 |
4276
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.
44
45When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis.
46
47**Plan**
48
49A research agent used during [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.
50
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
54
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.
56
57**General-purpose**
58
59A capable agent for complex, multi-step tasks that require both exploration and action.
60
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
64
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](https://code.claude.com/docs/en/agent-view.md); [which permission mode it starts in](https://code.claude.com/docs/en/agent-view.md#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
7777Built-in subagents are registered by default in interactive sessions. To restrict them:
7878
7979* To block a specific built-in type, add it to `permissions.deny` as shown in [Disable specific subagents](#disable-specific-subagents).
from line 175
175175
176176**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:
177177
178**macOS, Linux, WSL**
178> [tab] macOS, Linux, WSL
179>
180> ```bash theme={null}
181> claude --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> ```
179194
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```
194
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```
195> [tab] Windows PowerShell
196>
197> ```powershell theme={null}
198> claude --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> ```
213213
214214In [non-interactive mode](https://code.claude.com/docs/en/headless.md), `--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.
215215
No line in this hunk matches that.