Sub-Agents in Claude Code

Status: Production Ready ✅ Last Updated: 2026-01-14 Source: https://code.claude.com/docs/en/sub-agents

Sub-agents are specialized AI assistants that Claude Code can delegate tasks to. Each sub-agent has its own context window, configurable tools, and custom system prompt.

---

Why Use Sub-Agents: Context Hygiene

The primary value of sub-agents isn't specialization—it's keeping your main context clean.

Without agent (context bloat):

Main context accumulates:
├─ git status output (50 lines)
├─ npm run build output (200 lines)
├─ tsc --noEmit output (100 lines)
├─ wrangler deploy output (100 lines)
├─ curl health check responses
├─ All reasoning about what to do next
└─ Context: 📈 500+ lines consumed

With agent (context hygiene):

Main context:
├─ "Deploy to cloudflare"
├─ [agent summary - 30 lines]
└─ Context: 📊 ~50 lines consumed

Agent context (isolated):
├─ All verbose tool outputs
├─ All intermediate reasoning
└─ Discarded after returning summary

The math: A deploy workflow runs ~10 tool calls. That's 500+ lines in main context vs 30-line summary with an agent. Over a session, this compounds dramatically.

When this matters most:

• Repeatable workflows (deploy, migrate, audit, review)
• Verbose tool outputs (build logs, test results, API responses)
• Multi-step operations where only the final result matters
• Long sessions where context pressure builds up

Key insight: Use agents for workflows you repeat, not just for specialization. The context savings compound over time.

---

Built-in Sub-Agents

Claude Code includes three built-in sub-agents available out of the box:

Explore Agent

Fast, lightweight agent optimized for read-only codebase exploration.

Thoroughness levels (specify when invoking):

• quick - Fast searches, targeted lookups
• medium - Balanced speed and thoroughness
• very thorough - Comprehensive analysis across multiple locations

When Claude uses it: Searching/understanding codebase without making changes. Findings don't bloat the main conversation.

User: Where are errors from the client handled?
Claude: [Invokes Explore with "medium" thoroughness]
       → Returns: src/services/process.ts:712

Plan Agent

Specialized for plan mode research and information gathering.

When Claude uses it: In plan mode when researching codebase to create a plan. Prevents infinite nesting (sub-agents cannot spawn sub-agents).

General-Purpose Agent

Capable agent for complex, multi-step tasks requiring both exploration AND action.

When Claude uses it:

• Task requires both exploration and modification
• Complex reasoning needed to interpret search results
• Multiple strategies may be needed
• Task has multiple dependent steps

---

Creating Custom Sub-Agents

File Locations

When names conflict, project-level takes precedence.

⚠️ CRITICAL: Session Restart Required

Agents are loaded at session startup only. If you create new agent files during a session:

1. They won't appear in /agents
2. Claude won't be able to invoke them
3. Solution: Restart Claude Code session to discover new agents

This is the most common reason custom agents "don't work" - they were created after the session started.

File Format

Markdown files with YAML frontmatter:

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: default
skills: project-workflow
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Your sub-agent's system prompt goes here.

Include specific instructions, best practices, and constraints.

Configuration Fields

...