| title | Subagents |
|---|---|
| nav_title | Subagents |
| description | When to delegate, which agents ship built in, and how to write your own. |
| order | 3 |
A subagent is a copy of Claude sent off with one clearly scoped job. It works in its own context and reports back only the conclusion.
The point is that your main conversation doesn't get flooded. Ask "find every call site of validateUser in this repo" and, if the main agent searches itself, dozens of files end up in the context window. Delegate it and all that comes back is the list.
- Questions that require reading a lot of files — finding usages, untangling dependencies, counting where a pattern occurs.
- Independent work that can run in parallel — frontend, backend, and tests at the same time.
- The same thing from several angles — several agents each reviewing the same code.
Conversely: if you already know the file and the line, just say so. No need for the detour.
Delegated agents appear under SubAgents in the Activity panel with their tool activity streaming live. Open one to read its full transcript and final result. Background agents work the same way — you don't have to wait for them to finish to see what they're doing.
Available without any setup:
| Name | What it's for |
|---|---|
general-purpose |
The catch-all. Researching complex questions, searching for code, multi-step tasks |
Explore |
Fast codebase exploration. Find files by pattern, search code by keyword, answer "how does this part work" |
Plan |
The architect. Designs an implementation strategy and returns step-by-step plans, critical files, and trade-offs |
claude-code-guide |
Answers questions about Claude Code, the Agent SDK, and the Claude API themselves |
verification |
Sign-off before you call it done. Runs builds, tests, and linters and returns PASS / FAIL / PARTIAL with evidence |
statusline-setup |
Configures the Claude Code status line |
You can name one directly ("use Explore to find…") or let Claude decide who to send.
Open Settings → Agents. Three cards at the top show total agents, how many are active, and how many sources are in play. Below that, agents are grouped by source in a fixed order:
User → Project → Local → Managed → Plugin → CLI arg → Built-in
When two agents share a name, the higher source wins and the shadowed one is tagged "Overridden by X". Day to day, two groups matter:
- User — the ones you wrote, available in every project, stored in
~/.claude/agents/. - Project — scoped to the current project, stored in its
.claude/agents/, shipped with the repo.
Click any row for its detail page: model, effort, tool scope, and the full system prompt. Built-in and plugin agents are read-only and show a lock pill instead of edit controls.
Hover a row in the list and its actions appear on the right: Edit and Delete for user and project agents, Adjust model for built-in ones. The same controls sit in the top-right of the detail page.
Built-in agents each pin a default model — Explore and claude-code-guide run on Haiku, statusline-setup on Sonnet — chosen for speed and cost. If you care more about their output quality, you can swap that out.
Click Adjust model on the built-in agent's row, or the same button in the top-right of its detail page. Only two things are editable:
- Model — Built-in default, Inherit from parent, the Haiku / Sonnet / Opus / Fable aliases, or a model configured for the current provider.
- Reasoning effort — Built-in default, or low / medium / high / xhigh / max.
The system prompt, tool scope, and color stay fixed by Claude Code.
:::tip
"Built-in default" and "Inherit from parent" are not the same thing. For Explore, the first is the Haiku it ships pinned to; the second follows whatever model your main conversation is using. To go back to how it shipped, pick "Built-in default" or click Reset to built-in default.
:::
The override is written to builtInAgentOverrides in ~/.claude/settings.json and applies to every project. Resetting removes the entry entirely rather than leaving an empty shell behind in your config.
Agent configuration stores a model ID, not a provider. The picker lists models from the current provider. If you switch providers later, aliases resolve through the new provider's mapping, while a full model ID must also be supported by the new provider.
If you create a user agent with the same name (a hand-written file with name: Explore, say), it shadows the built-in one completely — changing the built-in's model then has no effect, and the dialog says so.
Click Create Agent in the top right. The fields:
- Scope — user or project. Choosing project asks you to confirm the target path.
- Name — 1–64 lowercase letters, digits, hyphens, or underscores, e.g.
code-reviewer. This is what the main agent calls it by. - Description — when the main agent should delegate to it. This is the field that matters most: it's what the main agent reads to decide whether to call this agent at all. Write it vaguely and the agent will never be used.
- System prompt — its responsibilities, boundaries, and expected output.
- Model — inherit from the main agent, choose a Haiku / Sonnet / Opus / Fable alias, or choose a model configured for the current provider. Simple repetitive work is faster and cheaper on Haiku.
- Effort — inherit, or set low / medium / high / xhigh / max. Models that don't support a level downgrade or ignore it.
- Tools — all tools, no tools, or a custom list. The custom picker groups built-in tools by read and search, modify files, execute commands, and workflow, with a free-text field below for MCP tool names or permission rules like
Bash(git:*). - Color — optional, purely for telling agents apart in the UI.
Saving writes a Markdown file into the matching directory and refreshes the current session. A failed refresh doesn't roll back the file — it still applies after a restart.
:::tip Grant only the tools the job needs. An agent whose job is to read code and report back doesn't need Write or Bash. Narrow the permissions and you narrow how far it can go wrong. :::
For the agent file format, source precedence, and inheritance rules, see Agent internals.