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

Agents and parallel work

MCP

Skills

Plugins

Artifacts

Automation

Guides

Troubleshooting

Built-in subagents

Quickstart: create your first subagent

​Built-in subagents

​Quickstart: create your first subagent

Built-in subagents

Quickstart: create your first subagent