Create custom subagents

Subagents are specialized AI assistants that handle specific types of tasks. Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again: the subagent does that work in its own context and returns only the summary. Define a custom subagent when you keep spawning the same kind of worker with the same instructions. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. 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 walks through a session where a subagent handles research in its own separate window.

Subagents work within a single session. To run many independent sessions in parallel and monitor them from one place, see background agents. For separate sessions that pass messages to each other, see cross-session messaging. For a coordinated team of sessions Claude spawns and supervises, see agent teams.

Subagents help you:

Preserve context by keeping exploration and implementation out of your main conversation
Enforce constraints by limiting which tools a subagent can use
Reuse configurations across projects with user-level subagents
Specialize behavior with focused system prompts for specific domains
Control costs by routing tasks to faster, cheaper models like Haiku

Claude uses each subagent’s description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it.

Built-in subagents

Claude Code includes built-in subagents that Claude automatically uses when appropriate. Each inherits the parent conversation’s permissions; most run with a restricted tool set. Explore and Plan skip your CLAUDE.md files and the parent session’s git status to keep research fast and inexpensive. Every other built-in and custom subagent loads both. For the full breakdown of what reaches a subagent, see what loads at startup.

Explore
Plan
General-purpose
Other

A fast, read-only agent optimized for searching and analyzing codebases.

Model: inherits from the main conversation, capped at Opus on the Claude API, so Explore never runs on a more expensive model than the one you already chose for the session
Tools: read-only tools; Write and Edit are denied
Purpose: file discovery, code search, codebase exploration

As of v2.1.198, Explore inherits the main conversation’s model instead of always running on Haiku. On the Claude API, the inherited model is capped at Opus: a main conversation on a higher tier runs Explore on Opus, and a main conversation on Sonnet or Haiku runs Explore on that same model. On any other provider, such as Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or Claude Platform on AWS, Explore inherits the main conversation’s model directly.A user or project subagent named Explore overrides the built-in and keeps its own model field, so define one with model: haiku to keep exploration on a lower-cost model.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.When invoking Explore, Claude specifies a thoroughness level: quick for targeted lookups, medium for balanced exploration, or very thorough for comprehensive analysis.

Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don’t need to use them directly.

Agent	Model	When Claude uses it
claude	Inherits	When a task doesn’t fit a more specialized agent. A catch-all with every tool available to subagents. Also the default agent for a dispatched background session; which permission mode it starts in depends on how the session was started
statusline-setup	Sonnet	When you run `/statusline` to configure your status line
claude-code-guide	Haiku	When you ask questions about Claude Code features

Built-in subagents are registered by default in interactive sessions. To restrict them:

To block a specific built-in type, add it to permissions.deny as shown in Disable specific subagents.
To prevent Claude from delegating to any subagent, deny the Agent tool itself with permissions.deny.
To remove only the built-in Explore and Plan subagents, set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude reads and explores files directly instead of delegating to them. Requires Claude Code v2.1.198 or later.
In non-interactive mode and the Agent SDK, set CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 to remove all built-in types and supply only your own.

An Agent tool call that omits subagent_type fails with subagent_type is required when the session has no general-purpose subagent to fall back on. Beyond these built-in subagents, you can create your own with custom prompts, tool restrictions, permission modes, hooks, and skills. The following sections show how to get started and customize subagents.

Quickstart: create your first subagent

Subagents are Markdown files with YAML frontmatter. To create one, ask Claude to write it for you, or write the file yourself. As of v2.1.198, the /agents command no longer opens the interactive creation wizard; running it prints a reminder to ask Claude or edit .claude/agents/ directly. Subagent files, frontmatter fields, and the .claude/agents/ and ~/.claude/agents/ locations are unchanged; only the terminal wizard is removed. This walkthrough creates a user-level subagent that reviews code and suggests improvements.

Ask Claude to create the subagent

In Claude Code, describe the subagent you want and where to save it:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude writes the file with a name, a description, a tools list, a model, and a system prompt.

Review the file

Open ~/.claude/agents/code-improver.md and confirm the frontmatter matches what you asked for. The result looks like this:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

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 compares the two.

Try it out

Ask Claude to delegate to the new subagent:

Use the code-improver agent to suggest improvements in this project

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).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.

You now have a subagent you can use in any project on your machine to analyze codebases and suggest improvements. You can also write subagent files by hand, define them via CLI flags, or distribute them through plugins. The following sections cover all configuration options.

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.

Configure subagents

A subagent’s file location determines who it’s available to, and its frontmatter determines what it can do. This section covers where subagent files live and every field they support.

Choose the subagent scope

Store subagent files in different locations depending on scope. When multiple subagents share the same name, Claude Code uses the one from the higher-priority location.

Location	Scope	Priority	How to create
Managed settings	Organization-wide	1 (highest)	Deployed via managed settings
`--agents` CLI flag	Current session	2	Pass JSON when launching Claude Code
`.claude/agents/`	Current project	3	Ask Claude, or create the file manually
`~/.claude/agents/`	All your projects	4	Ask Claude, or create the file manually
Plugin’s `agents/` directory	Where plugin is enabled	5 (lowest)	Installed with plugins

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. Project subagents are discovered by walking up from the current working directory, so every .claude/agents/ between there and the repository root is scanned. As of v2.1.178, when more than one of these nested directories defines the same name, Claude Code uses the definition closest to the working directory. When you add a directory with --add-dir or /add-dir, Claude Code also loads its .claude/agents/ folder, alongside your project subagents. See Additional directories for which other configuration types load from --add-dir. To share subagents across projects without --add-dir, use ~/.claude/agents/ or a plugin. User subagents (~/.claude/agents/) are personal subagents available in all your projects. Claude Code scans .claude/agents/ and ~/.claude/agents/ recursively, so you can organize definitions into subfolders such as agents/review/ or agents/research/. The subdirectory path doesn’t affect how a subagent is identified or invoked, because identity comes only from the name frontmatter field. Keep name values unique across the whole tree: if two files under the same .claude/agents/ directory, including its subfolders, declare the same name, Claude Code loads only one of them, chosen by filesystem read order rather than a documented precedence. Across nested project directories, the definition closest to the working directory wins, as described above. The /doctor setup checkup reports files in the same directory that share a name and proposes renaming or removing all but one. Before v2.1.205, /doctor opened a diagnostics screen that listed duplicates and showed which definition was active. Plugin agents/ directories are also scanned recursively. Unlike project and user scopes, a subfolder inside a plugin’s agents/ directory becomes part of the scoped identifier: a file at agents/review/security.md in plugin my-plugin registers as my-plugin:review:security. 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:

macOS, Linux, WSL
Windows PowerShell

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

The --agents flag accepts JSON with a prompt field plus these frontmatter fields: description, 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. Managed subagents are deployed by organization administrators. Place markdown files in .claude/agents/ inside the managed settings directory, using the same frontmatter format as project and user subagents. Managed definitions take precedence over project and user subagents with the same name. Plugin subagents come from plugins 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 for details on creating plugin subagents.

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 in settings.json or settings.local.json, but these rules apply to the entire session, not only the plugin subagent.

Subagent definitions from any of these scopes are also available to agent teams: when spawning a teammate, you can reference a subagent type and the teammate uses its tools and model, with the definition’s body appended to the teammate’s system prompt as additional instructions. See agent teams for which frontmatter fields apply on that path.

Write subagent files

Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:

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.Three cases still need a restart:

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.
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.
Sessions started with --disable-slash-commands don’t watch these directories at all.

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

The frontmatter defines the subagent’s metadata and configuration. The body becomes the system prompt that guides the subagent’s behavior. Subagents receive only this system prompt plus basic environment details like the working directory, not the full Claude Code system prompt. In non-interactive mode, pass --append-subagent-system-prompt to append your text to the end of every subagent’s system prompt, nested subagents included, apart from a forked subagent, which reuses the conversation’s own prompt. Requires Claude Code v2.1.205 or later. A subagent starts in the main conversation’s current working directory. Within a subagent, cd commands don’t persist between Bash or PowerShell tool calls and don’t affect the main conversation’s working directory. To give the subagent an isolated copy of the repository instead, set isolation: worktree. A subagent with isolation: worktree runs its Bash and PowerShell commands inside its worktree. A command whose working directory resolves to your main checkout instead, for example because the worktree directory was removed while the subagent was running, fails with an error. Before v2.1.203, such a command could run in the main checkout. This working-directory check covers the whole repository containing the directory you launched Claude Code from. When your session runs in a linked worktree of its own, the check also covers the main checkout that worktree is linked from. Before v2.1.210, the check covered only the launch directory itself. A command whose working directory resolved elsewhere in the same repository, such as the repository root when you launched Claude Code from a monorepo subdirectory, ran there instead of failing. For Bash commands, Claude Code also checks the command itself in two ways:

It blocks a command that redirects git into the main checkout.
It refuses a command whose shape it can’t verify stays inside the worktree. This refusal applies even to a command that runs no git.

The redirect vectors and the shape rules are listed under How Claude Code enforces isolation. PowerShell commands get only the working-directory check. Monitor commands go through the same working-directory and command-content checks as Bash commands. When 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.

Supported frontmatter fields

The following fields can be used in the YAML frontmatter. Only name and description are required.

Field	Required	Description
`name`	Yes	Unique identifier using lowercase letters and hyphens. Hooks receive this value as `agent_type`. The filename doesn’t have to match. Names can’t contain `:`, which is reserved for plugin-scoped identifiers such as `my-plugin:reviewer`. Claude Code doesn’t load a file whose name contains one and logs an error to the debug log. Before v2.1.218, such names were accepted
`description`	Yes	When Claude should delegate to this subagent
`tools`	No	Tools the subagent can use. Inherits every tool available to subagents if omitted. If no entry in the list resolves to a tool, the subagent usually fails to launch with an error naming the entries. To preload Skills into context, use the `skills` field rather than listing `Skill` here
`disallowedTools`	No	Tools to deny, removed from inherited or specified list
`model`	No	Model to use: `sonnet`, `opus`, `haiku`, `fable`, a full model ID (for example, `claude-opus-5`), or `inherit`. Defaults to `inherit`
`permissionMode`	No	Permission mode: `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, or `manual` as an alias for `default`. The `manual` alias requires Claude Code v2.1.200 or later. Ignored for plugin subagents
`maxTurns`	No	Maximum number of agentic turns before the subagent stops
`skills`	No	Skills to preload into the subagent’s context at startup. The full skill content is injected, not only the description. Subagents can still invoke unlisted project, user, and plugin skills through the Skill tool
`mcpServers`	No	MCP servers 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 as value. Ignored for plugin subagents
`hooks`	No	Lifecycle hooks scoped to this subagent. Ignored for plugin subagents
`memory`	No	Persistent memory scope: `user`, `project`, or `local`. Enables cross-session learning
`background`	No	Set to `true` to keep this subagent in the background even when Claude asks to run it in the foreground. Where fork mode is on, Claude Code already runs the subagents Claude spawns in the background
`effort`	No	Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model
`isolation`	No	Set to `worktree` to run the subagent in a temporary git worktree, giving it an isolated copy of the repository branched by default from your default branch rather than the parent session’s `HEAD`. The worktree is automatically cleaned up if the subagent makes no changes
`color`	No	Display color for the subagent in the task list and transcript. Accepts `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan`
`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 and skills are processed. Prepended to any user-provided prompt

Choose a model

The model field controls which AI model the subagent uses:

Model alias: use one of the available aliases: sonnet, opus, haiku, or fable
Full model ID: use a full model ID such as claude-opus-5 or claude-sonnet-5. Accepts the same values as the --model flag
inherit: use the same model as the main conversation
Omitted: defaults to inherit and uses the same model as the main conversation

When Claude invokes a subagent, it can also pass a model parameter for that specific invocation. Claude Code resolves the subagent’s model in this order:

The CLAUDE_CODE_SUBAGENT_MODEL environment variable, when set to a model alias or model ID
The per-invocation model parameter
The subagent definition’s model frontmatter
The main conversation’s model

As of v2.1.196, setting CLAUDE_CODE_SUBAGENT_MODEL to inherit is the same as leaving it unset: resolution continues with the per-invocation model parameter, then the frontmatter. In earlier versions, inherit forced subagents onto the main conversation’s model and ignored both of those sources. Claude Code checks the environment variable, per-invocation parameter, and frontmatter values against your organization’s availableModels allowlist. For a blocked value, it substitutes another model:

When the blocked value is a family alias such as opus, Claude Code runs the subagent on the newest version of that family the allowlist permits, following the same substitution rules and provider scope as /model. Before v2.1.222, Claude Code ran the subagent on the inherited model for a blocked family alias as well.
For any other blocked value, on providers where that substitution doesn’t operate, or when the allowlist permits no version of the family, Claude Code runs the subagent on the inherited model instead.

In interactive sessions, Claude Code shows a warning naming the requested model and the model the subagent runs on, for either substitution. A per-invocation model parameter also applies when the subagent is resumed or sent a follow-up message, so the subagent stays on that model. Before v2.1.211, resuming dropped the per-invocation value and the subagent reverted to its definition’s model field or, without one, the main conversation’s model. As of v2.1.198, subagents also inherit the main conversation’s extended thinking configuration: if thinking is on in your session, it’s on for the subagent, and if it’s off, it stays off. There is no per-subagent thinking setting. Before v2.1.198, subagents ran with extended thinking disabled regardless of the main conversation’s setting.

Control subagent capabilities

You can control what subagents can do through tool access, permission modes, and conditional rules.

Available tools

Subagents inherit the built-in tools and MCP tools available in the main conversation, narrowed by two filters: the first removes a short list of tools from every subagent, and the second reduces the built-in tool set for subagents that run in the background, which is the default. Forks skip both filters and receive the main conversation’s exact tool pool. The first filter removes these tools, even when listed in the tools field:

Agent, when the subagent is at the depth limit; in a fork the tool stays listed but returns an error instead of spawning
AskUserQuestion
EndConversation, which can end only the main conversation; see EndConversation tool behavior
EnterPlanMode
ExitPlanMode, unless the subagent’s permissionMode is plan
ScheduleWakeup
TaskOutput
WaitForMcpServers
Workflow

The second filter applies to subagents running in the background. Apart from Agent and ExitPlanMode, which follow the first filter’s conditions wherever the subagent runs, a background subagent keeps every MCP tool but only these built-in tools: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, and Artifact. Claude Code removes every other built-in tool from a background subagent, whether inherited or listed in the tools field, so the same definition can resolve to different tools in the foreground and the background. The removal reports no error unless it leaves the tools list resolving to nothing. ListAgents follows these filters like any built-in tool: a foreground subagent inherits it in sessions where cross-session messaging is enabled, and a background subagent doesn’t keep it. Teammates in agent teams additionally keep the task tools and cron tools: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete, and CronList. In a session without the Task tools, Claude Code doesn’t provide the task tools to subagents either, even when the subagent runs a different model. An in-process teammate follows your session the same way, while a teammate in its own split pane runs as a separate Claude Code process, so its own model decides. To restrict tools, use the tools field as an allowlist or the disallowedTools field as a denylist. This example uses tools to allow only Read, Grep, Glob, and Bash. The subagent can’t edit files, write files, or use any MCP tools:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

This example uses disallowedTools to inherit the subagent’s tool pool except Write and Edit. The subagent keeps Bash, MCP tools, and the rest of its pool:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

If both are set, disallowedTools is applied first, then tools is resolved against the remaining pool. A tool listed in both is removed. When nothing in the tools list resolves to a tool, for example because every entry is misspelled or names a tool that isn’t available to subagents, Claude Code usually refuses to launch the subagent and the Agent tool returns an error naming the unresolved entries; see Agent would be spawned with zero tools for the message and how to fix each entry. Before v2.1.208, that subagent launched with no tools and could return an empty or confusing result. Both fields accept MCP server-level patterns in addition to exact tool names: mcp__<server> or mcp__<server>__* grants or removes every tool from the named server. In disallowedTools, mcp__* also removes every MCP tool from any server. This example removes every tool from the github MCP server while keeping tools from other servers and the built-in tools in its pool:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

Restrict which subagents can be spawned

When 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.

Agents and parallel work

MCP

Skills

Plugins

Artifacts

Automation

Guides

Troubleshooting

Built-in subagents

Quickstart: create your first subagent

Configure subagents

Choose the subagent scope

Write subagent files

Supported frontmatter fields

Choose a model

Control subagent capabilities

Available tools

Restrict which subagents can be spawned

​Built-in subagents

​Quickstart: create your first subagent

​Configure subagents

​Choose the subagent scope

​Write subagent files

​Supported frontmatter fields

​Choose a model

​Control subagent capabilities

​Available tools

​Restrict which subagents can be spawned

Built-in subagents

Quickstart: create your first subagent

Configure subagents

Choose the subagent scope

Write subagent files

Supported frontmatter fields

Choose a model

Control subagent capabilities

Available tools

Restrict which subagents can be spawned