Built-in Subagents

Claude Code ships with five built-in subagents. They are not config files you write, they are hard-coded agent definitions that Claude spawns automatically when it recognizes the right pattern. Three of them (Explore, Plan, General-purpose) do the heavy lifting. Two (statusline-setup, claude-code-guide) handle housekeeping. You don't configure these, but you need to know what they do and when Claude will reach for them, otherwise you'll see agent output you didn't explicitly request and wonder where it came from.

What you'll learn

• Explore is a read-only research agent. It searches your codebase, reads files, and runs read-only shell commands, it cannot write, edit, or delete. Its model inherits from the parent but is capped at Opus.
• Plan enters plan mode to research and produce a markdown plan in .claude/plans/. It uses the same read-only constraint as Explore, then delivers a structured plan the parent can execute.
• General-purpose has the full toolset, read, write, edit, shell, git, everything the parent has. It's a clone of the parent minus the context baggage.
• Load order is automatic: Claude chooses which built-in agent to spawn based on the task pattern it sees. You don't invoke them by name, you give Claude a task and it decides.
• Set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 to prevent Claude from ever spawning Explore or Plan, useful in CI where research-only agents waste credits.

The problem

You ask Claude Code to "find where authentication logic is implemented across all our microservices and document every entry point." A single agent reads service 1, service 2, service 3 , each discovery piling into the context window. By service 5 the agent is 80% consumed by code it's already read and starts missing things. Then it tries to write the documentation from memory and invents function signatures it half-remembers.

Claude Code's answer: recognize that this is a research task, spawn Explore subagents (one per service directory), and let each one work in its own clean context. The parent receives summaries, not raw file dumps. The write step happens with fresh context.

The five built-in agents

Agent	Tools	Model	When Claude spawns it
Explore	Read, Glob, Grep, Bash (read-only commands)	Inherited from parent, capped at Opus	"Search the codebase for...", "Find all implementations of...", "Audit every service for..."
Plan	Read, Glob, Grep, Bash (read-only), Write (to .claude/plans/ only)	Inherited from parent	"Plan out the migration...", "Research the approach and write a plan...", anything asking for a plan before execution
General-purpose	All tools the parent has	Inherited from parent	"Split this work across agents...", "Delegate this full task to an agent...", any delegation where tool restrictions would break the task
statusline-setup	Shell (restricted)	Small/fast model	Internal, runs on session start to configure the status line. You won't see its output unless it fails
claude-code-guide	Read, Glob	Inherited from parent	Internal, handles /help and answers questions about Claude Code itself. Spawned when Claude needs to look up its own documentation

Explore in detail

Explore is the most frequently spawned built-in agent. Its defining constraint is read-only, it cannot modify files, run destructive shell commands, or make network calls to external services. This makes it safe to spawn liberally: even if the model hallucinates a dangerous command, Explore's tool restrictions block it.

The thoroughness parameter controls how deep Explore goes:

Thoroughness	Behavior	Best for
quick	Surface-level search, first matches only	"Find the config file for X"
medium	Searches multiple patterns, reads matching files	"Audit this module for SQL injection patterns"
very thorough	Exhaustive search across all directories, reads every match	"Map every API endpoint in this monorepo"

The model for Explore inherits from the parent session. If you're running Claude Opus, Explore gets Opus. If you're running Sonnet, Explore gets Sonnet. The practical cap is Opus, Explore will never exceed it even if the parent is on a larger model, because read-only research doesn't need frontier reasoning.

Plan in detail

Plan mode is Claude Code's answer to "think before you build." When Claude sees a task pattern that benefits from upfront research, migrations, architectural changes, cross-cutting refactors, it spawns the Plan subagent.

Plan operates exactly like Explore during research (read-only, same model inheritance, same thoroughness levels). The difference is what it produces: a markdown plan file written to .claude/plans/<plan-name>.md. The plan includes:

• A clear goal statement
• Research findings from the exploration phase
• Step-by-step implementation tasks
• Files that will be created or modified
• Risks and rollback considerations

After the plan is written, it opens in the parent session's review UI. You can approve it, edit it, or reject it. If approved, the parent agent executes the plan step by step, often delegating individual steps to General-purpose subagents.

General-purpose in detail

General-purpose is the workhorse. It has every tool the parent has. The only thing it doesn't have is the parent's accumulated context, it starts fresh for each task, which is both the feature (clean context) and the trade-off (it doesn't know what the parent discovered earlier unless you tell it in the delegation prompt).

General-purpose is what Claude spawns when you say "delegate this task to a subagent" without specifying restrictions. It's the right choice for any sub-task that needs write access, shell execution, or git operations.

When built-in agents run

You don't invoke built-in agents with a command. You give Claude a task:

Find every place in this project where we read from the database without a transaction wrapper.
For each match, tell me the file, line number, and function name.

Claude sees this and recognizes: research pattern → spawn Explore. You see tool calls for the Explore agent appear in the output, followed by the results.

The parent's role during subagent execution is to wait and collect. It doesn't feed context to the subagent, the subagent works independently. When the subagent finishes, its output is injected into the parent's context as a tool result.

Build it

Step 1: Trigger Explore with a research task

Start an interactive session:

claude

Give it a research task that spans multiple parts of your codebase:

Audit the entire project for hard-coded secrets (API keys, tokens, passwords).
Search in all file types ,  .py, .js, .yml, .env, .json, .tf.
For each match, report the file, line number, and whether it looks like a real secret or a placeholder.
Do not modify anything, this is a read-only audit.

You'll see output like ⏳ Explore agent searching... followed by the findings. Claude spawned Explore because the task matched the "search multiple locations for a pattern" signature.

Step 2: Force Plan mode

Explicitly ask for a plan:

Plan the migration of our authentication system from session-based to JWT.
Research the current implementation first, then write a plan to .claude/plans/jwt-migration.md.
Do not make any changes, plan only.

Claude spawns the Plan agent, which researches the codebase and writes a markdown plan. The plan opens in the review UI. You can inspect it before the parent starts executing.

Step 3: Disable Explore and Plan

For CI/CD environments or when you want total control:

export CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1
claude

With this set, Claude will never spawn Explore or Plan. It handles all work in the parent session or delegates to General-purpose subagents (if permitted).

What goes wrong

Mistake	How you notice it	The fix
Explore spawned for a task that needs writes	Explore returns research findings but you expected file edits	Explore is read-only by design. If the task needs writes, rephrase to either (a) start with "Research X, then implement Y" or (b) explicitly say "don't use Explore, do the work directly"
Plan mode for a trivial task	A plan file appears in .claude/plans/ for something that could have been done in 30 seconds	Claude's pattern matching sometimes over-triggers. Add "No plan needed, just do it" to the prompt, or set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 for the session
Explore exhausts credits on a large codebase	The audit takes 5 minutes and 200 tool calls, and the API bill is higher than expected	Use thoroughness: quick by saying "quick search only" in the prompt. For very large codebases, scope the search: "Only search the src/ directory"
General-purpose makes changes the parent didn't expect	You see file edits in the output that contradict the parent's earlier instructions	General-purpose has no context from the parent beyond the delegation prompt. Be explicit in the delegation: tell it what the parent has already done, what constraints apply, and what it must not touch
statusline-setup fails silently	The status line doesn't appear, or shows stale information	This is cosmetic, it doesn't affect agent behavior. Restart the session. If it persists, check ~/.claude/debug.log for the error

Confirm it worked

Use the following commands to confirm that Claude successfully spawns the Explore and Plan built-in subagents based on task patterns.

# Start a session
claude

# 1. Trigger Explore:
#    "Search the codebase for all TODO and FIXME comments. List file, line, and text."
#    Verify: you see "Explore agent" in the output, results are read-only.

# 2. Trigger Plan:
#    "Plan a refactor of the project's error handling. Research first, write the plan."
#    Verify: a file appears in .claude/plans/, parent asks for approval.

# 3. Verify disable works:
#    Exit, then: CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 claude
#    "Search for all TODO comments."
#    Verify: no Explore agent spawn: Claude searches directly or uses General-purpose.

# If all three patterns behave as expected, built-in subagents are working.

Next: Custom Subagents , writing your own specialized agents with restricted toolsets.