Text of code.claude.com › docs › en › sub-agents as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Create custom subagents - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. 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. It also sends its own requests, which count toward the same usage limits as your main conversation. 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, lower-cost 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. Those descriptions take up context, so keep them short. When the combined descriptions of your subagents, except the built-in ones, exceed 15,000 tokens, Claude Code shows a warning at startup with the total token count . Trim the description fields of your subagents, and move detail into each subagent’s system prompt, which only loads when that subagent runs.

Built-in subagents Claude Code includes built-in subagents that Claude automatically uses when appropriate. Each inherits the parent conversation’s permission rules; most run with a restricted tool set. Explore 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 load both, unless you set omitClaudeMd 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 . Explore Plan General-purpose Other A fast, read-only agent optimized for searching and analyzing codebases. Model : the parent conversation’s model. When the parent conversation runs Fable, Explore runs on Opus or stays on Fable, based on how you connect. With a Claude subscription, an Anthropic Console account, or an LLM gateway reached through ANTHROPIC_BASE_URL , Explore runs on the Opus model that the opus alias resolves to.

On Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, Claude Platform on AWS , or a Claude apps gateway , Explore stays on Fable. Tools : read-only tools; Write and Edit are denied Purpose : file discovery, code search, codebase exploration A user or project subagent 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 . 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.

A research agent used during plan mode to gather context before presenting a plan. Model : inherits from the parent conversation , unless you set CLAUDE_CODE_SUBAGENT_MODEL and force it onto every subagent Tools : read-only tools; Write and Edit are denied Purpose : codebase research for planning 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.

A capable agent for complex, multi-step tasks that require both exploration and action. Model : the parent conversation’s model by default, following the model order Tools : every tool available to subagents Purpose : complex research, multi-step operations, code modifications Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.

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 None of its own; follows the model order 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 . 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 . This walkthrough creates a user-level subagent that reviews code and suggests improvements. 1 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. 2 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 improvem

The rest of this page is on the live site.