Create custom subagents

• 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

​

Built-in subagents

• 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.

​

Quickstart: create your first subagent

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.

---
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 improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

Configure subagents

​

Choose the subagent scope

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

​

Write subagent files

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

​

Supported frontmatter fields

​

Choose a model

• Model alias: use one of the available aliases: sonnet, opus, haiku, or fable
• Full model ID: use a full model ID such as claude-opus-4-8 or claude-sonnet-5. Accepts the same values as the --model flag
• inherit: use the same model as the main conversation
• Omitted: defaults to inherit and uses the same model as the main conversation

1. The CLAUDE_CODE_SUBAGENT_MODEL environment variable, when set to a model alias or model ID
2. The per-invocation model parameter
3. The subagent definition’s model frontmatter
4. The main conversation’s model

​

Control subagent capabilities

​

Available tools

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, unless the subagent’s permissionMode is plan
• ScheduleWakeup
• WaitForMcpServers

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

​

Restrict which subagents can be spawned

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

tools: Agent, Read, Bash

​

Scope MCP servers to a subagent

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• --strict-mcp-config and --bare
• Enterprise managed MCP configuration
• allowedMcpServers and deniedMcpServers policies

​

Permission modes

​

Preload skills into subagents

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

​

Enable persistent memory

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

• The subagent’s system prompt includes instructions for reading and writing to the memory directory.
• The subagent’s system prompt also includes the first 200 lines or 25KB of MEMORY.md in the memory directory, whichever comes first, with instructions to curate MEMORY.md if it exceeds that limit.
• Read, Write, and Edit tools are automatically enabled so the subagent can manage its memory files.

Persistent memory tips

• project is the recommended default scope. It makes subagent knowledge shareable via version control.
• Ask the subagent to consult its memory before starting work: “Review this PR, and check your memory for patterns you’ve seen before.”
• Ask the subagent to update its memory after completing a task: “Now that you’re done, save what you learned to your memory.” Over time, this builds a knowledge base that makes the subagent more effective.
• Include memory instructions directly in the subagent’s markdown file so it proactively maintains its own knowledge base:
  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

​

Conditional rules with hooks

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

​

Disable specific subagents

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

claude --disallowedTools "Agent(Explore)"

​

Define hooks for subagents

• In the subagent’s frontmatter: define hooks that run only while that subagent is active
• In settings.json: define hooks that run in the main session when subagents start or stop

​

Hooks in subagent frontmatter

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

Project-level hooks for subagent events

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

​

Work with subagents

​

Understand automatic delegation

​

Invoke subagents explicitly

• Natural language: name the subagent in your prompt; Claude decides whether to delegate
• @-mention: guarantees the subagent runs for one task
• Session-wide: the whole session uses that subagent’s system prompt, tool restrictions, and model via the --agent flag or the agent setting

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

Run subagents in foreground or background

• Foreground subagents block the main conversation until complete. Permission prompts are passed through to you as they come up.
• Background subagents run concurrently while you continue working. As of v2.1.186, when a background subagent reaches a tool call that needs permission, the prompt surfaces in your main session and names the subagent that is asking. Approve to let the subagent continue, or press Esc to deny that one tool call without stopping the subagent. Before v2.1.186, background subagents auto-denied any tool call that would have prompted.

• Ask Claude to run a task in the background or in the foreground
• Press Ctrl+B to background a running task

​

API errors in subagents

• Foreground: if a rate limit, overload, or server error cuts off a subagent that already produced text output, the Agent tool returns that partial output with a note that the subagent was cut off and didn’t finish its task. A subagent that produced nothing, or whose only output was tool calls, fails with Agent terminated early due to an API error, followed by the error detail. In v2.1.199, a rate limit, overload, or server error that cut off the tool-calls-only shape returned an empty partial result containing only the cut-off note instead.
• Background: the subagent is marked failed, and the message Claude receives when it ends names the API error and includes the subagent’s last output, so partial work isn’t lost.

​

Common patterns

​

Isolate high-volume operations

Use a subagent to run the test suite and report only the failing tests with their error messages

​

Run parallel research

Research the authentication, database, and API modules in parallel using separate subagents

​

Chain subagents

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

​

Choose between subagents and main conversation

• The task needs frequent back-and-forth or iterative refinement
• Multiple phases share significant context, such as planning, implementation, and testing
• You’re making a quick, targeted change
• Latency matters. Subagents start fresh and may need time to gather context

• The task produces verbose output you don’t need in your main context
• You want to enforce specific tool restrictions or permissions
• The work is self-contained and can return a summary

​

Spawn nested subagents

​

Manage subagent context

​

What loads at startup

• System prompt: the agent’s own prompt plus environment details that Claude Code appends, not the full Claude Code system prompt. Custom subagents define theirs in the markdown body or prompt field. Built-in agents have predefined prompts.
• Task message: the delegation prompt Claude writes when it hands off the work.
• CLAUDE.md and memory: every level of the memory hierarchy the main conversation loads, including ~/.claude/CLAUDE.md, project rules, CLAUDE.local.md, and managed policy files. The built-in Explore and Plan agents skip this.
• Git status: a snapshot taken at the start of the parent session. Absent when the working directory isn’t a Git repository or when includeGitInstructions is false. Explore and Plan skip it regardless.
• Preloaded skills: full content of any skill named in the agent’s skills field. Built-in agents don’t preload skills.
• Sibling roster: a system reminder listing main and every other named agent in the session, each a valid to value for SendMessage. Requires Claude Code v2.1.206 or later. The roster appears only when the subagent’s tools include SendMessage and at least one other agent has a name, whether Claude named it when spawning it or it runs as an agent team teammate. It is a snapshot taken when the subagent starts, so agents named later don’t appear.

​

Resume subagents

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• Main conversation compaction: when the main conversation compacts, subagent transcripts are unaffected. They’re stored in separate files.
• Session persistence: subagent transcripts persist within their session. You can resume a subagent after restarting Claude Code by resuming the same session.
• Automatic cleanup: transcripts are cleaned up based on the cleanupPeriodDays setting, which defaults to 30 days.

​

Auto-compaction

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

​

Fork the current conversation

• Claude can spawn a fork by requesting the fork subagent type explicitly. Spawns without a subagent type still use the general-purpose subagent, and named subagents such as Explore still spawn as before.
• Every subagent spawn runs in the background, whether it is a fork or a named subagent. Set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS to 1 to keep spawns synchronous.

/fork draft unit tests for the parser changes so far

​

Observe and steer running forks

​

How forks differ from named subagents

​

Limitations

​

Example subagents

​

Code reviewer

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

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

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​

Debugger

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

​

Data scientist

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​

Database query validator

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Next steps

• Distribute subagents with plugins to share subagents across teams or projects
• Run Claude Code programmatically with the Agent SDK for CI/CD and automation
• Use MCP servers to give subagents access to external tools and data