Name	Name	Last commit message	Last commit date
parent directory ..
README.md	README.md
clean-code-reviewer.md	clean-code-reviewer.md
code-reviewer.md	code-reviewer.md
data-scientist.md	data-scientist.md
debugger.md	debugger.md
documentation-writer.md	documentation-writer.md
implementation-agent.md	implementation-agent.md
secure-reviewer.md	secure-reviewer.md
test-engineer.md	test-engineer.md

Subagents - Complete Reference Guide

Subagents are specialized AI assistants that Claude Code can delegate tasks to. Each subagent has a specific purpose, uses its own context window separate from the main conversation, and can be configured with specific tools and a custom system prompt.

Overview
Key Benefits
File Locations
Configuration
Built-in Subagents
Managing Subagents
Using Subagents
Resumable Agents
Chaining Subagents
Persistent Memory for Subagents
Background Subagents
Worktree Isolation
Restrict Spawnable Subagents
claude agents CLI Command
Agent Teams (Experimental)
Plugin Subagent Security
Architecture
Context Management
When to Use Subagents
Best Practices
Example Subagents in This Folder
Installation Instructions
Related Concepts

Overview

Subagents enable delegated task execution in Claude Code by:

Creating isolated AI assistants with separate context windows
Providing customized system prompts for specialized expertise
Enforcing tool access control to limit capabilities
Preventing context pollution from complex tasks
Enabling parallel execution of multiple specialized tasks

Each subagent operates independently with a clean slate, receiving only the specific context necessary for their task, then returning results to the main agent for synthesis.

Quick Start: Use the /agents command to create, view, edit, and manage your subagents interactively.

Key Benefits

Benefit	Description
Context preservation	Operates in separate context, preventing pollution of main conversation
Specialized expertise	Fine-tuned for specific domains with higher success rates
Reusability	Use across different projects and share with teams
Flexible permissions	Different tool access levels for different subagent types
Scalability	Multiple agents work on different aspects simultaneously

File Locations

Subagent files can be stored in multiple locations with different scopes:

Priority	Type	Location	Scope
1 (highest)	CLI-defined	Via `--agents` flag (JSON)	Session only
2	Project subagents	`.claude/agents/`	Current project
3	User subagents	`~/.claude/agents/`	All projects
4 (lowest)	Plugin agents	Plugin `agents/` directory	Via plugins

When duplicate names exist, higher-priority sources take precedence.

Configuration

File Format

Subagents are defined in YAML frontmatter followed by the system prompt in markdown:

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
disallowedTools: tool4  # Optional - explicitly disallowed tools
model: sonnet  # Optional - sonnet, opus, haiku, or inherit
permissionMode: default  # Optional - permission mode
maxTurns: 20  # Optional - limit agentic turns
skills: skill1, skill2  # Optional - skills to preload into context
mcpServers: server1  # Optional - MCP servers to make available
memory: user  # Optional - persistent memory scope (user, project, local)
background: false  # Optional - run as background task
effort: high  # Optional - reasoning effort (low, medium, high, max)
isolation: worktree  # Optional - git worktree isolation
initialPrompt: "Start by analyzing the codebase"  # Optional - auto-submitted first turn
hooks:  # Optional - component-scoped hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier (lowercase letters and hyphens)
`description`	Yes	Natural language description of purpose. Include "use PROACTIVELY" to encourage automatic invocation
`tools`	No	Comma-separated list of specific tools. Omit to inherit all tools. Supports `Agent(agent_name)` syntax to restrict spawnable subagents
`disallowedTools`	No	Comma-separated list of tools the subagent must not use
`model`	No	Model to use: `sonnet`, `opus`, `haiku`, full model ID, or `inherit`. Defaults to configured subagent model
`permissionMode`	No	`default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`
`maxTurns`	No	Maximum number of agentic turns the subagent can take
`skills`	No	Comma-separated list of skills to preload. Injects full skill content into the subagent's context at startup
`mcpServers`	No	MCP servers to make available to the subagent
`hooks`	No	Component-scoped hooks (PreToolUse, PostToolUse, Stop)
`memory`	No	Persistent memory directory scope: `user`, `project`, or `local`
`background`	No	Set to `true` to always run this subagent as a background task
`effort`	No	Reasoning effort level: `low`, `medium`, `high`, or `max`
`isolation`	No	Set to `worktree` to give the subagent its own git worktree
`initialPrompt`	No	Auto-submitted first turn when the subagent runs as the main agent

Tool Configuration Options

Option 1: Inherit All Tools (omit the field)

---
name: full-access-agent
description: Agent with all available tools
---

Option 2: Specify Individual Tools

---
name: limited-agent
description: Agent with specific tools only
tools: Read, Grep, Glob, Bash
---

Option 3: Conditional Tool Access

---
name: conditional-agent
description: Agent with filtered tool access
tools: Read, Bash(npm:*), Bash(test:*)
---

CLI-Based Configuration

Define subagents for a single session using the --agents flag with JSON format:

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"
  }
}'

JSON Format for --agents flag:

{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

Priority of Agent Definitions:

Agent definitions are loaded with this priority order (first match wins):

CLI-defined - --agents flag (session only, JSON)
Project-level - .claude/agents/ (current project)
User-level - ~/.claude/agents/ (all projects)
Plugin-level - Plugin agents/ directory

This allows CLI definitions to override all other sources for a single session.

Built-in Subagents

Claude Code includes several built-in subagents that are always available:

Agent	Model	Purpose
general-purpose	Inherits	Complex, multi-step tasks
Plan	Inherits	Research for plan mode
Explore	Haiku	Read-only codebase exploration (quick/medium/very thorough)
Bash	Inherits	Terminal commands in separate context
statusline-setup	Sonnet	Configure status line
Claude Code Guide	Haiku	Answer Claude Code feature questions

General-Purpose Subagent

Property	Value
Model	Inherits from parent
Tools	All tools
Purpose	Complex research tasks, multi-step operations, code modifications

When used: Tasks requiring both exploration and modification with complex reasoning.

Plan Subagent

Property	Value
Model	Inherits from parent
Tools	Read, Glob, Grep, Bash
Purpose	Used automatically in plan mode to research codebase

When used: When Claude needs to understand the codebase before presenting a plan.

Explore Subagent

Property	Value
Model	Haiku (fast, low-latency)
Mode	Strictly read-only
Tools	Glob, Grep, Read, Bash (read-only commands only)
Purpose	Fast codebase searching and analysis

When used: When searching/understanding code without making changes.

Thoroughness Levels - Specify the depth of exploration:

"quick" - Fast searches with minimal exploration, good for finding specific patterns
"medium" - Moderate exploration, balanced speed and thoroughness, default approach
"very thorough" - Comprehensive analysis across multiple locations and naming conventions, may take longer

Bash Subagent

Property	Value
Model	Inherits from parent
Tools	Bash
Purpose	Execute terminal commands in a separate context window

When used: When running shell commands that benefit from isolated context.

Statusline Setup Subagent

Property	Value
Model	Sonnet
Tools	Read, Write, Bash
Purpose	Configure the Claude Code status line display

When used: When setting up or customizing the status line.

Claude Code Guide Subagent

Property	Value
Model	Haiku (fast, low-latency)
Tools	Read-only
Purpose	Answer questions about Claude Code features and usage

When used: When users ask questions about how Claude Code works or how to use specific features.

Managing Subagents

Using the `/agents` Command (Recommended)

/agents

This provides an interactive menu to:

View all available subagents (built-in, user, and project)
Create new subagents with guided setup
Edit existing custom subagents and tool access
Delete custom subagents
See which subagents are active when duplicates exist

Direct File Management

# Create a project subagent
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively
run the appropriate tests. If tests fail, analyze the failures and fix
them while preserving the original test intent.
EOF

# Create a user subagent (available in all projects)
mkdir -p ~/.claude/agents

Using Subagents

Automatic Delegation

Claude proactively delegates tasks based on:

Task description in your request
The description field in subagent configurations
Current context and available tools

To encourage proactive use, include "use PROACTIVELY" or "MUST BE USED" in your description field:

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
---

Explicit Invocation

You can explicitly request a specific subagent:

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

@-Mention Invocation

Use the @ prefix to guarantee a specific subagent is invoked (bypasses automatic delegation heuristics):

> @"code-reviewer (agent)" review the auth module

Session-Wide Agent

Run an entire session using a specific agent as the main agent:

# Via CLI flag
claude --agent code-reviewer

# Via settings.json
{
  "agent": "code-reviewer"
}

Listing Available Agents

Use the claude agents command to list all configured agents from all sources:

claude agents

Resumable Agents

Subagents can continue previous conversations with full context preserved:

# Initial invocation
> Use the code-analyzer agent to start reviewing the authentication module
# Returns agentId: "abc123"

# Resume the agent later
> Resume agent abc123 and now analyze the authorization logic as well

Use cases:

Long-running research across multiple sessions
Iterative refinement without losing context
Multi-step workflows maintaining context

Chaining Subagents

Execute multiple subagents in sequence:

> First use the code-analyzer subagent to find performance issues,
  then use the optimizer subagent to fix them

This enables complex workflows where the output of one subagent feeds into another.

Persistent Memory for Subagents

The memory field gives subagents a persistent directory that survives across conversations. This allows subagents to build up knowledge over time, storing notes, findings, and context that persist between sessions.

Memory Scopes

Scope	Directory	Use Case
`user`	`~/.claude/agent-memory/<name>/`	Personal notes and preferences across all projects
`project`	`.claude/agent-memory/<name>/`	Project-specific knowledge shared with the team
`local`	`.claude/agent-memory-local/<name>/`	Local project knowledge not committed to version control

How It Works

The first 200 lines of MEMORY.md in the memory directory are automatically loaded into the subagent's system prompt
The Read, Write, and Edit tools are automatically enabled for the subagent to manage its memory files
The subagent can create additional files in its memory directory as needed

Example Configuration

---
name: researcher
memory: user
---

You are a research assistant. Use your memory directory to store findings,
track progress across sessions, and build up knowledge over time.

Check your MEMORY.md file at the start of each session to recall previous context.

graph LR
    A["Subagent<br/>Session 1"] -->|writes| M["MEMORY.md<br/>(persistent)"]
    M -->|loads into| B["Subagent<br/>Session 2"]
    B -->|updates| M
    M -->|loads into| C["Subagent<br/>Session 3"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#e1f5fe,stroke:#333,color:#333
    style M fill:#f3e5f5,stroke:#333,color:#333

Background Subagents

Subagents can run in the background, freeing up the main conversation for other tasks.

Configuration

Set background: true in the frontmatter to always run the subagent as a background task:

---
name: long-runner
background: true
description: Performs long-running analysis tasks in the background
---

Keyboard Shortcuts

Shortcut	Action
`Ctrl+B`	Background a currently running subagent task
`Ctrl+F`	Kill all background agents (press twice to confirm)

Disabling Background Tasks

Set the environment variable to disable background task support entirely:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Worktree Isolation

The isolation: worktree setting gives a subagent its own git worktree, allowing it to make changes independently without affecting the main working tree.

Configuration

---
name: feature-builder
isolation: worktree
description: Implements features in an isolated git worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

How It Works

graph TB
    Main["Main Working Tree"] -->|spawns| Sub["Subagent with<br/>Isolated Worktree"]
    Sub -->|makes changes in| WT["Separate Git<br/>Worktree + Branch"]
    WT -->|no changes| Clean["Auto-cleaned"]
    WT -->|has changes| Return["Returns worktree<br/>path and branch"]

    style Main fill:#e1f5fe,stroke:#333,color:#333
    style Sub fill:#f3e5f5,stroke:#333,color:#333
    style WT fill:#e8f5e9,stroke:#333,color:#333
    style Clean fill:#fff3e0,stroke:#333,color:#333
    style Return fill:#fff3e0,stroke:#333,color:#333

The subagent operates in its own git worktree on a separate branch
If the subagent makes no changes, the worktree is automatically cleaned up
If changes exist, the worktree path and branch name are returned to the main agent for review or merging

Restrict Spawnable Subagents

You can control which subagents a given subagent is allowed to spawn by using the Agent(agent_type) syntax in the tools field. This provides a way to allowlist specific subagents for delegation.

Note: In v2.1.63, the Task tool was renamed to Agent. Existing Task(...) references still work as aliases.

Example

---
name: coordinator
description: Coordinates work between specialized agents
tools: Agent(worker, researcher), Read, Bash
---

You are a coordinator agent. You can delegate work to the "worker" and
"researcher" subagents only. Use Read and Bash for your own exploration.

In this example, the coordinator subagent can only spawn the worker and researcher subagents. It cannot spawn any other subagents, even if they are defined elsewhere.

`claude agents` CLI Command

The claude agents command lists all configured agents grouped by source (built-in, user-level, project-level):

claude agents

This command:

Shows all available agents from all sources
Groups agents by their source location
Indicates overrides when an agent at a higher priority level shadows one at a lower level (e.g., a project-level agent with the same name as a user-level agent)

Agent Teams (Experimental)

Agent Teams coordinate multiple Claude Code instances working together on complex tasks. Unlike subagents (which are delegated subtasks returning results), teammates work independently with their own context and communicate directly through a shared mailbox system.

Note: Agent Teams is experimental and requires Claude Code v2.1.32+. Enable it before use.

Subagents vs Agent Teams

Aspect	Subagents	Agent Teams
Delegation model	Parent delegates subtask, waits for result	Team lead assigns work, teammates execute independently
Context	Fresh context per subtask, results distilled back	Each teammate maintains its own persistent context
Coordination	Sequential or parallel, managed by parent	Shared task list with automatic dependency management
Communication	Return values only	Inter-agent messaging via mailbox
Session resumption	Supported	Not supported with in-process teammates
Best for	Focused, well-defined subtasks	Large multi-file projects requiring parallel work

Enabling Agent Teams

Set the environment variable or add it to your settings.json:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Starting a team

Once enabled, ask Claude to work with teammates in your prompt:

User: Build the authentication module. Use a team — one teammate for the API endpoints,
      one for the database schema, and one for the test suite.

Claude will create the team, assign tasks, and coordinate the work automatically.

Display modes

Control how teammate activity is displayed:

Mode	Flag	Description
Auto	`--teammate-mode auto`	Automatically chooses the best display mode for your terminal
In-process	`--teammate-mode in-process`	Shows teammate output inline in the current terminal (default)
Split-panes	`--teammate-mode tmux`	Opens each teammate in a separate tmux or iTerm2 pane

claude --teammate-mode tmux

You can also set the display mode in settings.json:

{
  "teammateMode": "tmux"
}

Note: Split-pane mode requires tmux or iTerm2. It is not available in VS Code terminal, Windows Terminal, or Ghostty.

Navigation

Use Shift+Down to navigate between teammates in split-pane mode.

Team Configuration

Team configurations are stored at ~/.claude/teams/{team-name}/config.json.

Architecture

graph TB
    Lead["Team Lead<br/>(Coordinator)"]
    TaskList["Shared Task List<br/>(Dependencies)"]
    Mailbox["Mailbox<br/>(Messages)"]
    T1["Teammate 1<br/>(Own Context)"]
    T2["Teammate 2<br/>(Own Context)"]
    T3["Teammate 3<br/>(Own Context)"]

    Lead -->|assigns tasks| TaskList
    Lead -->|sends messages| Mailbox
    TaskList -->|picks up work| T1
    TaskList -->|picks up work| T2
    TaskList -->|picks up work| T3
    T1 -->|reads/writes| Mailbox
    T2 -->|reads/writes| Mailbox
    T3 -->|reads/writes| Mailbox
    T1 -->|updates status| TaskList
    T2 -->|updates status| TaskList
    T3 -->|updates status| TaskList

    style Lead fill:#e1f5fe,stroke:#333,color:#333
    style TaskList fill:#fff9c4,stroke:#333,color:#333
    style Mailbox fill:#f3e5f5,stroke:#333,color:#333
    style T1 fill:#e8f5e9,stroke:#333,color:#333
    style T2 fill:#e8f5e9,stroke:#333,color:#333
    style T3 fill:#e8f5e9,stroke:#333,color:#333

Key components:

Team Lead: The main Claude Code session that creates the team, assigns tasks, and coordinates
Shared Task List: A synchronized list of tasks with automatic dependency tracking
Mailbox: An inter-agent messaging system for teammates to communicate status and coordinate
Teammates: Independent Claude Code instances, each with their own context window

Task assignment and messaging

The team lead breaks work into tasks and assigns them to teammates. The shared task list handles:

Automatic dependency management — tasks wait for their dependencies to complete
Status tracking — teammates update task status as they work
Inter-agent messaging — teammates send messages via the mailbox for coordination (e.g., "Database schema is ready, you can start writing queries")

Plan approval workflow

For complex tasks, the team lead creates an execution plan before teammates begin work. The user reviews and approves the plan, ensuring the team's approach aligns with expectations before any code changes are made.

Hook events for teams

Agent Teams introduce two additional hook events:

Event	Fires When	Use Case
`TeammateIdle`	A teammate finishes its current task and has no pending work	Trigger notifications, assign follow-up tasks
`TaskCompleted`	A task in the shared task list is marked complete	Run validation, update dashboards, chain dependent work

Best practices

Team size: Keep teams at 3-5 teammates for optimal coordination
Task sizing: Break work into tasks that take 5-15 minutes each — small enough to parallelize, large enough to be meaningful
Avoid file conflicts: Assign different files or directories to different teammates to prevent merge conflicts
Start simple: Use in-process mode for your first team; switch to split-panes once comfortable
Clear task descriptions: Provide specific, actionable task descriptions so teammates can work independently

Limitations

Experimental: Feature behavior may change in future releases
No session resumption: In-process teammates cannot be resumed after a session ends
One team per session: Cannot create nested teams or multiple teams in a single session
Fixed leadership: The team lead role cannot be transferred to a teammate
Split-pane restrictions: tmux/iTerm2 required; not available in VS Code terminal, Windows Terminal, or Ghostty
No cross-session teams: Teammates exist only within the current session

Warning: Agent Teams is experimental. Test with non-critical work first and monitor teammate coordination for unexpected behavior.

Plugin Subagent Security

Plugin-provided subagents have restricted frontmatter capabilities for security. The following fields are not allowed in plugin subagent definitions:

hooks - Cannot define lifecycle hooks
mcpServers - Cannot configure MCP servers
permissionMode - Cannot override permission settings

This prevents plugins from escalating privileges or executing arbitrary commands through subagent hooks.

Architecture

High-Level Architecture

graph TB
    User["User"]
    Main["Main Agent<br/>(Coordinator)"]
    Reviewer["Code Reviewer<br/>Subagent"]
    Tester["Test Engineer<br/>Subagent"]
    Docs["Documentation<br/>Subagent"]

    User -->|asks| Main
    Main -->|delegates| Reviewer
    Main -->|delegates| Tester
    Main -->|delegates| Docs
    Reviewer -->|returns result| Main
    Tester -->|returns result| Main
    Docs -->|returns result| Main
    Main -->|synthesizes| User

Subagent Lifecycle

sequenceDiagram
    participant User
    participant MainAgent as Main Agent
    participant CodeReviewer as Code Reviewer<br/>Subagent
    participant Context as Separate<br/>Context Window

    User->>MainAgent: "Build new auth feature"
    MainAgent->>MainAgent: Analyze task
    MainAgent->>CodeReviewer: "Review this code"
    CodeReviewer->>Context: Initialize clean context
    Context->>CodeReviewer: Load reviewer instructions
    CodeReviewer->>CodeReviewer: Perform review
    CodeReviewer-->>MainAgent: Return findings
    MainAgent->>MainAgent: Incorporate results
    MainAgent-->>User: Provide synthesis

Context Management

graph TB
    A["Main Agent Context<br/>50,000 tokens"]
    B["Subagent 1 Context<br/>20,000 tokens"]
    C["Subagent 2 Context<br/>20,000 tokens"]
    D["Subagent 3 Context<br/>20,000 tokens"]

    A -->|Clean slate| B
    A -->|Clean slate| C
    A -->|Clean slate| D

    B -->|Results only| A
    C -->|Results only| A
    D -->|Results only| A

    style A fill:#e1f5fe
    style B fill:#fff9c4
    style C fill:#fff9c4
    style D fill:#fff9c4

Key Points

Each subagent gets a fresh context window without the main conversation history
Only the relevant context is passed to the subagent for their specific task
Results are distilled back to the main agent
This prevents context token exhaustion on long projects

Performance Considerations

Context efficiency - Agents preserve main context, enabling longer sessions
Latency - Subagents start with clean slate and may add latency gathering initial context

Key Behaviors

No nested spawning - Subagents cannot spawn other subagents
Background permissions - Background subagents auto-deny any permissions that are not pre-approved
Backgrounding - Press Ctrl+B to background a currently running task
Transcripts - Subagent transcripts are stored at ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
Auto-compaction - Subagent context auto-compacts at ~95% capacity (override with CLAUDE_AUTOCOMPACT_PCT_OVERRIDE environment variable)

When to Use Subagents

Scenario	Use Subagent	Why
Complex feature with many steps	Yes	Separate concerns, prevent context pollution
Quick code review	No	Unnecessary overhead
Parallel task execution	Yes	Each subagent has own context
Specialized expertise needed	Yes	Custom system prompts
Long-running analysis	Yes	Prevents main context exhaustion
Single task	No	Adds latency unnecessarily

Best Practices

Design Principles

Do:

Start with Claude-generated agents - Generate initial subagent with Claude, then iterate to customize
Design focused subagents - Single, clear responsibilities rather than one doing everything
Write detailed prompts - Include specific instructions, examples, and constraints
Limit tool access - Grant only necessary tools for the subagent's purpose
Version control - Check project subagents into version control for team collaboration

Don't:

Create overlapping subagents with same roles
Give subagents unnecessary tool access
Use subagents for simple, single-step tasks
Mix concerns in one subagent's prompt
Forget to pass necessary context

System Prompt Best Practices

Be Specific About Role

You are an expert code reviewer specializing in [specific areas]

Define Priorities Clearly

Review priorities (in order):
1. Security Issues
2. Performance Problems
3. Code Quality

Specify Output Format

For each issue provide: Severity, Category, Location, Description, Fix, Impact

Include Action Steps

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Tool Access Strategy

Start Restrictive: Begin with only essential tools
Expand Only When Needed: Add tools as requirements demand
Read-Only When Possible: Use Read/Grep for analysis agents
Sandboxed Execution: Limit Bash commands to specific patterns

Example Subagents in This Folder

This folder contains ready-to-use example subagents:

1. Code Reviewer (`code-reviewer.md`)

Purpose: Comprehensive code quality and maintainability analysis

Tools: Read, Grep, Glob, Bash

Specialization:

Security vulnerability detection
Performance optimization identification
Code maintainability assessment
Test coverage analysis

Use When: You need automated code reviews with focus on quality and security

2. Test Engineer (`test-engineer.md`)

Purpose: Test strategy, coverage analysis, and automated testing

Tools: Read, Write, Bash, Grep

Specialization:

Unit test creation
Integration test design
Edge case identification
Coverage analysis (>80% target)

Use When: You need comprehensive test suite creation or coverage analysis

3. Documentation Writer (`documentation-writer.md`)

Purpose: Technical documentation, API docs, and user guides

Tools: Read, Write, Grep

Specialization:

API endpoint documentation
User guide creation
Architecture documentation
Code comment improvement

Use When: You need to create or update project documentation

4. Secure Reviewer (`secure-reviewer.md`)

Purpose: Security-focused code review with minimal permissions

Tools: Read, Grep

Specialization:

Security vulnerability detection
Authentication/authorization issues
Data exposure risks
Injection attack identification

Use When: You need security audits without modification capabilities

5. Implementation Agent (`implementation-agent.md`)

Purpose: Full implementation capabilities for feature development

Tools: Read, Write, Edit, Bash, Grep, Glob

Specialization:

Feature implementation
Code generation
Build and test execution
Codebase modification

Use When: You need a subagent to implement features end-to-end

6. Debugger (`debugger.md`)

Purpose: Debugging specialist for errors, test failures, and unexpected behavior

Tools: Read, Edit, Bash, Grep, Glob

Specialization:

Root cause analysis
Error investigation
Test failure resolution
Minimal fix implementation

Use When: You encounter bugs, errors, or unexpected behavior

7. Data Scientist (`data-scientist.md`)

Purpose: Data analysis expert for SQL queries and data insights

Tools: Bash, Read, Write

Specialization:

SQL query optimization
BigQuery operations
Data analysis and visualization
Statistical insights

Use When: You need data analysis, SQL queries, or BigQuery operations

Installation Instructions

Method 1: Using /agents Command (Recommended)

/agents

Then:

Select 'Create New Agent'
Choose project-level or user-level
Describe your subagent in detail
Select tools to grant access (or leave blank to inherit all)
Save and use

Method 2: Copy to Project

Copy the agent files to your project's .claude/agents/ directory:

# Navigate to your project
cd /path/to/your/project

# Create agents directory if it doesn't exist
mkdir -p .claude/agents

# Copy all agent files from this folder
cp /path/to/04-subagents/*.md .claude/agents/

# Remove the README (not needed in .claude/agents)
rm .claude/agents/README.md

Method 3: Copy to User Directory

For agents available in all your projects:

# Create user agents directory
mkdir -p ~/.claude/agents

# Copy agents
cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/
cp /path/to/04-subagents/debugger.md ~/.claude/agents/
# ... copy others as needed

Verification

After installation, verify the agents are recognized:

/agents

You should see your installed agents listed alongside the built-in ones.

File Structure

project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md
│       ├── test-engineer.md
│       ├── documentation-writer.md
│       ├── secure-reviewer.md
│       ├── implementation-agent.md
│       ├── debugger.md
│       └── data-scientist.md
└── ...

Related Concepts

Related Features

Slash Commands - Quick user-invoked shortcuts
Memory - Persistent cross-session context
Skills - Reusable autonomous capabilities
MCP Protocol - Real-time external data access
Hooks - Event-driven shell command automation
Plugins - Bundled extension packages

Comparison with Other Features

Feature	User-Invoked	Auto-Invoked	Persistent	External Access	Isolated Context
Slash Commands	Yes	No	No	No	No
Subagents	Yes	Yes	No	No	Yes
Memory	Auto	Auto	Yes	No	No
MCP	Auto	Yes	No	Yes	No
Skills	Yes	Yes	No	No	No

Integration Pattern

graph TD
    User["User Request"] --> Main["Main Agent"]
    Main -->|Uses| Memory["Memory<br/>(Context)"]
    Main -->|Queries| MCP["MCP<br/>(Live Data)"]
    Main -->|Invokes| Skills["Skills<br/>(Auto Tools)"]
    Main -->|Delegates| Subagents["Subagents<br/>(Specialists)"]

    Subagents -->|Use| Memory
    Subagents -->|Query| MCP
    Subagents -->|Isolated| Context["Clean Context<br/>Window"]

Additional Resources

Official Subagents Documentation
CLI Reference - --agents flag and other CLI options
Plugins Guide - For bundling agents with other features
Skills Guide - For auto-invoked capabilities
Memory Guide - For persistent context
Hooks Guide - For event-driven automation

Last updated: March 2026

This guide covers complete subagent configuration, delegation patterns, and best practices for Claude Code.

FilesExpand file tree

04-subagents

Directory actions

More options

Directory actions

More options

Latest commit

History

04-subagents

Folders and files

parent directory

README.md

Subagents - Complete Reference Guide

Table of Contents

Overview

Key Benefits

File Locations

Configuration

File Format

Configuration Fields

Tool Configuration Options

CLI-Based Configuration

Built-in Subagents

General-Purpose Subagent

Plan Subagent

Explore Subagent

Bash Subagent

Statusline Setup Subagent

Claude Code Guide Subagent

Managing Subagents

Using the /agents Command (Recommended)

Direct File Management

Using Subagents

Automatic Delegation

Explicit Invocation

@-Mention Invocation

Session-Wide Agent

Listing Available Agents

Resumable Agents

Chaining Subagents

Persistent Memory for Subagents

Memory Scopes

How It Works

Example Configuration

Background Subagents

Configuration

Keyboard Shortcuts

Disabling Background Tasks

Worktree Isolation

Configuration

How It Works

Restrict Spawnable Subagents

Example

claude agents CLI Command

Agent Teams (Experimental)

Subagents vs Agent Teams

Enabling Agent Teams

Starting a team

Display modes

Navigation

Team Configuration

Architecture

Task assignment and messaging

Plan approval workflow

Hook events for teams

Best practices

Limitations

Plugin Subagent Security

Architecture

High-Level Architecture

Subagent Lifecycle

Context Management

Key Points

Performance Considerations

Key Behaviors

When to Use Subagents

Best Practices

Design Principles

System Prompt Best Practices

Tool Access Strategy

Using the `/agents` Command (Recommended)

`claude agents` CLI Command

1. Code Reviewer (`code-reviewer.md`)

2. Test Engineer (`test-engineer.md`)

3. Documentation Writer (`documentation-writer.md`)

4. Secure Reviewer (`secure-reviewer.md`)

5. Implementation Agent (`implementation-agent.md`)

6. Debugger (`debugger.md`)

7. Data Scientist (`data-scientist.md`)