Subagents — Specialized AI Workers

When you ask Claude Code to investigate your authentication module, run the test suite, and then fix failing tests, everything happens in one conversation. Every file read, every command output, every intermediate result accumulates in the same context window. By the time Claude gets to fixing the tests, the context is cluttered with exploration output it no longer needs.

Subagents solve this. They are specialized AI instances that Claude spawns to handle specific tasks in isolated contexts. Each subagent gets its own context window, its own system prompt, and a defined set of tools. When the subagent finishes, only a summary of its results returns to the main conversation -- keeping your primary context clean and focused.

Think of subagents as function calls to other AI instances. You describe the task, the subagent works autonomously, and you get back the result without paying the context cost of every intermediate step.

Built-in Subagent Types

Claude Code ships with three built-in subagents that it automatically delegates to when appropriate. You do not need to configure anything -- Claude recognizes when a task fits a subagent's profile and delegates accordingly.

Explore

The Explore subagent is a fast, read-only agent optimized for codebase navigation. It runs on Haiku for low-latency responses and has access only to read-only tools (Glob, Grep, Read). It cannot edit or write files.

"Search the codebase and find every file that imports the AuthService class"

Claude delegates this to Explore because it requires searching across many files without making changes. The exploration happens in Explore's isolated context, and only the summarized findings return to your main conversation.

When invoking Explore, Claude specifies a thoroughness level:

• Quick -- targeted lookups for specific files or patterns
• Medium -- balanced exploration across related modules
• Very thorough -- comprehensive analysis spanning the entire codebase

Plan

The Plan subagent is a research agent used during plan mode to gather context before presenting an implementation plan. It inherits the model from your main conversation and has read-only tool access (no Write or Edit).

When you activate plan mode and ask Claude to design an approach, it delegates the codebase research to Plan. The subagent reads files, traces dependencies, and maps out the relevant code -- then returns its findings so Claude can synthesize them into a coherent plan.

"I want to add WebSocket support to the notification system. Enter plan mode
and design an approach."

Claude's Plan subagent researches the existing notification system, identifies integration points, and feeds its findings back. You receive a structured plan without your main context being filled with every file the subagent read.

General-Purpose

The general-purpose subagent is a full-capability agent with access to all tools, including Bash, Write, and Edit. It inherits the model from your main conversation and handles complex, multi-step tasks that require both exploration and modification.

"Use a subagent to run the full test suite and fix any failing tests"

This task requires reading test files, executing commands, interpreting output, and editing code -- a combination that only the general-purpose subagent can handle. The test output (which can be enormous) stays in the subagent's context, and you get back a summary of what failed and what was fixed.

Choosing the Right Built-in Subagent

Claude automatically selects the right subagent based on the task. You can also explicitly request one:

"Use the Explore subagent to map out the database schema across all migration files"

When to Use Subagents

Not every task warrants a subagent. The overhead of spawning a separate context and summarizing results means subagents add latency compared to doing the work inline. Use them when the benefits outweigh the cost.

Use subagents when:

• The task produces verbose output -- Test suites, log analysis, and documentation fetches generate output you do not need cluttering your main context.
• You want parallel investigation -- Spawn multiple subagents to research authentication, database, and API modules simultaneously.
• You need tool restrictions -- A code review subagent that can read but not modify files enforces discipline.
• The work is self-contained -- Tasks with clear inputs and outputs that do not require back-and-forth with you.

Stay in the main conversation when:

• You need iterative refinement -- Tasks requiring frequent back-and-forth with you are awkward through a subagent.
• Context is shared across phases -- If planning and implementation need the same context, splitting them wastes effort.
• The task is quick -- Simple edits or single-file changes do not justify the subagent overhead.
• Latency matters -- Subagents need time to build their own context from scratch.

Creating Custom Subagents

The built-in subagents cover common patterns, but custom subagents let you define specialized workers tailored to your project. Custom subagents are Markdown files with YAML frontmatter stored in the .claude/agents/ directory.

Subagent File Structure

A subagent file has two parts: YAML frontmatter for configuration and a Markdown body that becomes the system prompt.

---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: sonnet
---
 
You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
 
Review checklist:
- Code clarity and readability
- Proper error handling
- No exposed secrets or API keys
- Input validation
- Test coverage
 
Provide feedback by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
 
Include specific examples of how to fix issues.

Creating Subagents with /agents

The easiest way to create a subagent is through the interactive /agents command:

Use the code-reviewer subagent to review my recent changes

Key Frontmatter Fields

The description field is critical -- Claude uses it to decide when to delegate tasks. Write it as a clear statement of the subagent's purpose, optionally including "use proactively" to encourage automatic delegation.

Tool Restrictions and Permission Modes

One of the most powerful aspects of custom subagents is controlling what they can and cannot do. This lets you enforce safety constraints and create focused, predictable workers.

Tool Allowlists

The tools field specifies exactly which tools a subagent can access:

---
name: safe-researcher
description: Research agent that can explore but never modify code
tools: Read, Grep, Glob
---

This subagent can search and read files but cannot execute commands, edit files, or write new files. If it attempts a restricted operation, the tool call fails.

Tool Denylists

When you want a subagent to inherit most tools but exclude a few, use disallowedTools:

---
name: careful-coder
description: Implements features but cannot run arbitrary bash commands
disallowedTools: Bash
---

This subagent can read and edit files but cannot execute shell commands -- useful when you want code modifications without the risk of unintended side effects from scripts.

Permission Modes

The permissionMode field controls how the subagent handles permission prompts:

For most custom subagents, stick with default or dontAsk. Reserve bypassPermissions for trusted automation scripts where you have reviewed the subagent's prompt and tool access carefully.

Conditional Validation with Hooks

For fine-grained control beyond simple allowlists, use PreToolUse hooks. This lets a subagent have access to a tool but validates each invocation:

---
name: db-reader
description: Execute read-only database queries for analysis and reporting
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.

The validation script receives the command as JSON via stdin and exits with code 2 to block write operations (INSERT, UPDATE, DELETE, DROP). This gives you tool access with guardrails -- the subagent can run Bash commands, but only ones that pass your validation.

Subagent Communication and Context

Understanding how information flows between the main conversation and subagents helps you use them effectively.

Information Flow

1. Main agent sends a task -- Claude describes what the subagent should do, including any relevant context
2. Subagent works autonomously -- It reads files, runs commands, and reasons independently in its own context
3. Results return summarized -- The subagent's findings are compressed into a summary that returns to the main conversation

The subagent does not see your full conversation history. It receives only the task description, its own system prompt, and basic environment details (working directory, etc.).

Foreground vs. Background Execution

Subagents can run in two modes:

• Foreground (blocking) -- The main conversation waits until the subagent finishes. Permission prompts pass through to you.
• Background (concurrent) -- The subagent runs while you continue working. Claude pre-approves permissions before launching. Press Ctrl+B to background a running subagent.

Background subagents are ideal for long-running tasks like test suites or large-scale searches. If a background subagent fails due to missing permissions, you can resume it in the foreground.

Persistent Memory

Custom subagents can maintain memory across sessions with the memory field:

---
name: code-reviewer
description: Reviews code with growing knowledge of project patterns
memory: project
---
 
You are a code reviewer. As you review code, update your agent memory
with patterns, conventions, and recurring issues you discover.

The memory scope determines where the knowledge is stored:

• user (~/.claude/agent-memory/<name>/) -- learnings apply across all projects
• project (.claude/agent-memory/<name>/) -- project-specific, shareable via version control
• local (.claude/agent-memory-local/<name>/) -- project-specific, not checked into version control

When memory is enabled, the subagent automatically gets Read, Write, and Edit tools for its memory directory, and its system prompt includes instructions for maintaining a MEMORY.md file. Over time, the subagent builds institutional knowledge that makes it more effective.

CLAUDE.md Access

Subagents can access your project's CLAUDE.md and any project context files. This means project conventions, coding standards, and architectural decisions are available to every subagent automatically. Custom subagents can supplement this with their own system prompt for domain-specific instructions.

Practical Patterns

Parallel Research

Investigate multiple areas of a codebase simultaneously:

Research the authentication, database, and API modules in parallel
using separate subagents. Summarize how each module handles errors.

Claude spawns three subagents that work independently. Each explores its area and returns findings. Claude then synthesizes a unified summary. This is faster than sequential investigation and keeps all the exploration output out of your main context.

Chained Workflows

Use subagents in sequence where each step builds on the previous:

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

The code-reviewer finds the issues, its results return to Claude, and Claude passes the relevant findings to the optimizer subagent with clear instructions on what to fix.

Cost Optimization with Model Selection

Route simple tasks to cheaper, faster models:

---
name: quick-search
description: Fast codebase searches for simple lookups
tools: Read, Grep, Glob
model: haiku
---

By assigning Haiku to routine search tasks and reserving Opus or Sonnet for complex reasoning, you reduce costs without sacrificing quality where it matters.

---
name: security-auditor
description: Audits code for security vulnerabilities, exposed secrets, and unsafe patterns. Use proactively after code changes or before deployments.
tools: Read, Grep, Glob
model: sonnet
---
 
You are a security auditor. When invoked, scan the codebase for:
 
1. **Exposed secrets**: API keys, tokens, passwords in source files
2. **Injection vulnerabilities**: SQL injection, XSS, command injection
3. **Authentication issues**: Missing auth checks, weak token validation
4. **Dependency risks**: Known vulnerable packages in lock files
5. **Unsafe patterns**: eval(), dangerouslySetInnerHTML, shell exec with user input
 
For each finding, report:
- Severity: Critical / High / Medium / Low
- File and line number
- Description of the vulnerability
- Recommended fix
 
Start by scanning for exposed secrets (grep for API_KEY, SECRET, PASSWORD, TOKEN
in non-test files), then check for injection patterns, then review auth flows.

Use the security-auditor subagent to audit the src/ directory

Disabling Subagents

If a built-in subagent is not useful for your workflow, you can disable it in your settings:

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

Or via the CLI flag:

claude --disallowedTools "Task(Explore)"

This prevents Claude from delegating to the specified subagents. Use this when a subagent consistently makes poor decisions for your particular codebase or when you want full control over delegation.

Next Steps

You now know how to delegate work to specialized subagents within a single session. But what happens when you need multiple agents working in parallel across separate sessions, communicating with each other in real time? The next lesson covers Agent Teams -- Claude Code's system for orchestrating coordinated multi-agent workflows at scale.

Resources:

• Claude Code Subagents Documentation
• Run /agents in Claude Code to manage your subagents interactively
• Example subagents in the official documentation cover code reviewers, debuggers, data scientists, and database validators