Claude Code Subagents: Official Documentation Reference (2026)

This is a structured reference for Claude Code subagents based on the official Anthropic documentation (May 2026). If you came here looking for a deep-dive on what subagents are, when to use them, and the full configuration surface, you are in the right place.

For best-practices and design patterns, see Claude Code Subagents: Best Practices. This reference focuses on what the official docs actually say.

What Are Subagents?

Subagents are specialized AI assistants that handle specific types of tasks within a single Claude Code session. Each subagent:

• Runs in its own context window (separate from the parent conversation)
• Has a custom system prompt that focuses its behavior
• Operates with specific tool access (can be restricted)
• Maintains independent permissions
• Returns only a summary to the parent conversation

Use a subagent 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 result.

Subagents work within a single session. For parallel independent sessions, see background agents. For communicating sessions, see agent teams.

Built-in Subagents

Claude Code ships with several built-in subagents that Claude uses automatically when appropriate.

Explore

A fast, read-only agent optimized for codebase search and analysis.

• Model: Haiku (fast, low-latency)
• Tools: Read-only (Write and Edit are denied)
• Purpose: File discovery, code search, codebase exploration
• Special behavior: Skips CLAUDE.md and parent session git status for speed
• Thoroughness levels: quick, medium, very thorough

Plan

A research agent used during plan mode to gather context before presenting a plan.

• Model: Inherits from main conversation
• Tools: Read-only (Write and Edit denied)
• Purpose: Codebase research for planning
• Special behavior: Skips CLAUDE.md and parent session git status (same as Explore)

General-purpose

A capable agent for complex multi-step tasks requiring both exploration and action.

• Model: Inherits from main conversation
• Tools: All tools
• Purpose: Complex research, multi-step operations, code modifications

Other Built-ins

Creating Custom Subagents

Subagents are defined in Markdown files with YAML frontmatter. Two ways to create:

1. /agents command — Interactive UI (recommended)
2. Manually create .md file — For automation/version control

Quickstart (via /agents)

/agents

1. Switch to Library tab
2. Select Create new agent
3. Choose location: Personal (saves to ~/.claude/agents/), Project (saves to .claude/agents/), or Managed
4. Select Generate with Claude and describe the subagent
5. Select tools (Read-only / All / Custom)
6. Select model (Sonnet, Haiku, Opus, or Inherit)
7. Choose a color (for visual identification in UI)
8. Configure memory (User scope or None)
9. Save

The subagent is available immediately.

Manual Creation (YAML Frontmatter)

Create a Markdown file at ~/.claude/agents/my-agent.md (user scope) or .claude/agents/my-agent.md (project scope):

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: sonnet
color: blue
---

You are a senior code reviewer. Focus on:
1. Code quality and readability
2. Security vulnerabilities
3. Performance issues
4. Best practices

For each issue found, provide:
- File and line reference
- Current code snippet
- Suggested improvement
- Reasoning

Subagent Scope and Priority

Subagents can be defined in multiple locations. When duplicates exist, higher-priority wins.

Project subagents (.claude/agents/) — Check into version control for team sharing. User subagents (~/.claude/agents/) — Personal subagents across all projects.

Claude Code scans .claude/agents/ and ~/.claude/agents/ recursively. Subfolders don’t affect identity — the name frontmatter field is the only identifier.

Naming conflict warning: If two files in the same scope declare the same name, Claude Code keeps one and discards the other without warning.

Plugin Scope Identifier

Plugin subagents get scoped identifiers. A file at agents/review/security.md in plugin my-plugin is registered as my-plugin:review:security.

Full Frontmatter Reference

---
name: my-agent              # Required. Unique identifier
description: When to use    # Required. Helps Claude decide when to delegate
tools:                       # Optional. Default: inherit all
  - Read
  - Grep
  - Bash
model: sonnet                # Optional. sonnet, haiku, opus, inherit, default
color: blue                  # Optional. UI background color
permission-mode: ask         # Optional. ask, accept-edits, plan-mode, bypass
hooks:                       # Optional. Subagent-specific hooks
  PostToolUse:
    - matcher: Write
      command: prettier
skills:                      # Optional. Skills to load
  - skill-name
load-claude-md: true         # Optional. Default: true (built-ins differ)
allowed-paths:               # Optional. Restrict path access
  - "src/**"
---

name Field

• Required
• Must be unique within scope (case-sensitive)
• Used in Use the {name} agent to ... invocations
• Plugin subagents use scoped form: plugin-name:subfolder:name

description Field

• Required
• Claude reads this to decide when to delegate
• Best practices: Be specific, include trigger words like “use proactively”, “expert in”, “specialized for”

tools Field

• Optional. Default: inherit from parent conversation
• Can be array of tool names or * for all
• Common restriction patterns:
  • Read-only: [Read, Grep, Glob, WebFetch]
  • Build-only: [Read, Grep, Bash]
  • Write-only: [Read, Write, Edit]

model Field

• Options: sonnet, haiku, opus, inherit, default
• inherit (default behavior) uses the parent’s model
• haiku is recommended for read-heavy subagents (faster, cheaper)
• opus for complex reasoning

permission-mode Field

• ask — Prompts for confirmation
• accept-edits — Auto-accepts edits
• plan-mode — Forces plan mode
• bypass — No prompts (use carefully)

What Loads at Startup

When a subagent activates, the following load:

This is the key reason Explore and Plan are fast — they skip the heavyweight context.

Persistent Memory for Subagents

Subagents can maintain their own memory across conversations:

• Storage: ~/.claude/agent-memory/{agent-name}/
• Configuration: Choose “User scope” memory when creating subagent
• Contents: MEMORY.md index + topic files Claude writes

Example use: A code-reviewer subagent accumulates codebase patterns and recurring issues across reviews.

To disable memory: Choose “None” during creation, or set auto-memory-enabled: false in frontmatter.

Working with Subagents

Explicit Invocation

Use the code-reviewer agent to review this PR.

Claude delegates to the named subagent.

Implicit Delegation

If you write a task that matches a subagent’s description, Claude may auto-delegate. The clearer the description, the more reliable the auto-routing.

Forking the Current Conversation

You can fork the current conversation into a subagent:

/fork code-reviewer

The subagent receives the current conversation state and continues with its own system prompt.

Multiple Subagents in Parallel

Claude can spawn multiple subagents that work on different parts of a task simultaneously. The main conversation coordinates:

Use 3 review agents in parallel:
1. security-reviewer for OWASP issues
2. perf-reviewer for performance concerns
3. style-reviewer for code style

Merge the results into a single report.

CLI-Defined Subagents

Pass JSON to --agents flag when launching:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors.",
    "prompt": "You are an expert debugger."
  }
}'

These exist only for the session, not saved to disk.

Tool Restrictions Pattern Library

Read-only Reviewer

tools:
  - Read
  - Grep
  - Glob
  - WebFetch

Build-only Worker

tools:
  - Read
  - Grep
  - Bash
permission-mode: ask

Test Runner

tools:
  - Read
  - Bash
hooks:
  PostToolUse:
    - matcher: Bash
      command: "npm run test"

Documentation Writer

tools:
  - Read
  - Write
  - Edit
allowed-paths:
  - "docs/**"
  - "README.md"

Hooks for Subagents

Subagents can have their own hooks that fire during subagent execution:

hooks:
  PreToolUse:
    - matcher: Bash
      command: "logger -t claude-code 'Subagent running bash'"
  PostToolUse:
    - matcher: Write|Edit
      command: "prettier --write {file}"
  Stop:
    - command: "echo 'Subagent finished' >> ~/agent.log"

These hooks fire only when this subagent is active (not the parent conversation).

Skills for Subagents

Subagents can load skills like the parent conversation:

skills:
  - testing
  - api-design

Skills loaded by a subagent are scoped to that subagent’s context window.

What Subagents CAN’T Do

• Cannot spawn other subagents (prevents infinite nesting)
• Cannot persist state between sessions (only memory directory does)
• Cannot access tools outside their tools whitelist
• Cannot communicate with each other within a single session (use agent teams for that)

Debugging Subagents

Check Which Subagents Are Available

/agents

The Library tab shows all available subagents and where each is defined.

View Subagent Activity

/agents

The Running tab shows live subagents, their current task, and lets you stop them.

Logs

Subagent activity is logged to:

• ~/.claude/logs/agents/{session-id}/{agent-name}.log

Use this to debug why a subagent did or didn’t activate.

InstructionsLoaded Hook

hooks:
  InstructionsLoaded:
    - command: "echo 'Loaded: {instructions}' >> ~/agent-debug.log"

This shows what context the subagent received at startup.

Example Subagents

code-reviewer

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes for quality, security, and best practices.
tools:
  - Read
  - Grep
  - Glob
model: sonnet
color: blue
---

You are a senior code reviewer specializing in:
- Code readability and maintainability
- Security vulnerabilities (OWASP Top 10)
- Performance optimization
- Language-specific best practices

For each file reviewed:
1. List issues found, prioritized by severity
2. Show problematic code snippet
3. Suggest concrete improvement
4. Explain reasoning

Skip cosmetic issues. Focus on what would catch a senior reviewer's attention.

test-runner

---
name: test-runner
description: Runs tests and analyzes failures. Use when test commands fail or for test coverage analysis.
tools:
  - Read
  - Bash
  - Grep
model: haiku
color: green
---

You are a test execution specialist. When invoked:

1. Run the relevant test command (npm test, pytest, etc.)
2. If failures occur, analyze the output
3. Identify root causes (not just symptoms)
4. Suggest fixes with file:line references

For passing tests, report coverage and flag uncovered branches.

research-agent

---
name: research-agent
description: Web research specialist. Use when you need up-to-date documentation, library comparisons, or technical research.
tools:
  - WebFetch
  - WebSearch
  - Read
  - Write
model: sonnet
color: purple
---

You are a technical research specialist. When invoked:

1. Search for authoritative sources (official docs preferred)
2. Cross-reference multiple sources
3. Synthesize findings into actionable summary
4. Cite sources with URLs
5. Note any version-specific information

Avoid AI-generated summaries; prefer primary sources.

Related Articles

• Claude Code Subagents: Best Practices
• Claude Code Plugins: The Complete 2026 Reference
• Claude Code Hooks: The Complete 2026 Production Reference
• 15 Best Claude Code Skills
• Does Claude Code Support AGENTS.md?

FAQ

What’s the difference between subagents and skills?

Skills are reusable instruction modules invoked on demand. Subagents are specialized AI assistants with their own context window, tool restrictions, and system prompt. Skills extend the main conversation’s behavior; subagents create isolated execution environments.

Can subagents spawn other subagents?

No. Subagents cannot spawn other subagents. This prevents infinite nesting. If you need parallel work, the parent conversation must spawn multiple subagents directly.

How do I share subagents across projects?

Put them in ~/.claude/agents/ (user scope) for personal use across projects. For team sharing, use plugins or check .claude/agents/ into git.

What model should I use for read-only subagents?

Haiku (fast, cheap). It’s optimized for low-latency read operations. Reserve Sonnet/Opus for subagents requiring complex reasoning.

Can subagents have their own CLAUDE.md?

Subagents read the project + user CLAUDE.md by default (except Explore and Plan, which skip them for speed). To disable, set load-claude-md: false in frontmatter.

How do I prevent subagents from making destructive changes?

Restrict the tools field to read-only tools, or set permission-mode: ask to require confirmation for sensitive operations.

Where are subagent logs?

~/.claude/logs/agents/{session-id}/{agent-name}.log — useful for debugging why a subagent activated (or didn’t).

Can I use subagents with the Agent SDK?

Yes. The Agent SDK exposes the same subagent system. Programmatically invoke subagents from your own automation scripts.