Subagents — Specialized AI Workers

Subagents are specialized Claude instances that handle specific tasks in their own context window, so they don’t pollute your main conversation with logs, search results, or file contents you won’t need again.

---

When to Use a Subagent

Use a subagent when a side task would flood your main conversation. The subagent does the work, returns only a summary, and discards everything else.

Benefits:

• Preserve context — keep exploration out of your main conversation
• Enforce constraints — limit which tools are available
• Reuse — define once, available in all projects
• Specialize — focused system prompts for specific domains
• Control costs — route simple tasks to Haiku

---

Built-in Subagents

Claude Code includes these automatically:

Subagent	Model	Purpose
Explore	Haiku (fast)	Read-only codebase search. No Write/Edit.
Plan	Inherits parent	Research during plan mode. Read-only.
General-purpose	Inherits parent	Complex multi-step tasks, can read + edit
statusline-setup	Sonnet	When you run /statusline
claude-code-guide	Haiku	Questions about Claude Code features

To block a specific built-in: add it to permissions.deny in settings. To block ALL subagents: deny the Agent tool itself.

---

Create Your First Subagent

Using /agents (recommended)

/agents

Opens a tabbed interface:

• Running tab — live and recent subagents, stop/open them
• Library tab — view, create, edit, delete subagents

Steps:

1. Open Library tab → Create new agent → Personal
2. Choose Generate with Claude, describe what you want
3. Select tools (e.g., read-only: just Read/Grep/Glob)
4. Select model (Haiku=fast/cheap, Sonnet=balanced, Opus=powerful)
5. Choose a color (visual identification in UI)
6. Configure memory (None or User scope for persistent learning)
7. Save with s or Enter

---

Subagent File Format

Subagents are markdown files with YAML frontmatter:

---
name: code-reviewer
description: Analyzes code for quality issues, security vulnerabilities, and improvements. Use proactively after any code change.
model: sonnet
tools:
  - Read
  - Glob
  - Grep
color: blue
isolation: worktree
---

You are an expert code reviewer focused on:
1. Security vulnerabilities
2. Performance issues
3. Code clarity and maintainability

For each issue: explain the problem, show the current code, provide an improved version.

---

Subagent Scopes (Where to Store Files)

Location	Scope	Priority
Managed settings	Organization-wide	1 (highest)
--agents CLI flag	Current session only	2
.claude/agents/	Current project	3
~/.claude/agents/	All your projects	4
Plugin agents/ dir	Where plugin is enabled	5 (lowest)

Project subagents (.claude/agents/) → check into git so your team shares them. User subagents (~/.claude/agents/) → personal, all projects.

Subagents are discovered recursively — organize into subfolders freely. Identity comes from the name field, not the file path.

---

Supported Frontmatter Fields

---
name: my-agent           # Required. Unique identifier.
description: ...         # Required. Claude reads this to decide when to delegate.
model: haiku             # haiku | sonnet | opus (or full model ID)
tools:                   # List of allowed tools (inherits all if omitted)
  - Read
  - Grep
  - Glob
color: blue              # Visual color in UI
isolation: worktree      # Runs in isolated git worktree
memory: user             # Persistent memory across sessions
---

---

CLI-Defined Subagents (Temporary)

Pass JSON via --agents for a session-only subagent (useful for testing):

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on 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."
  }
}'

---

Invoke Subagents Explicitly

Claude invokes subagents automatically based on their description. You can also invoke explicitly:

Use the code-reviewer agent to check auth.py

For plugin subagents with scoped names:

Use the my-plugin:review:security agent

---

Isolating Subagents with Worktrees

To prevent parallel subagents from editing the same files simultaneously:

---
name: feature-builder
isolation: worktree
---

Or ask Claude at runtime: “use worktrees for your agents”

Each subagent gets its own git worktree that is automatically cleaned up when the subagent finishes (if no changes were made).

---

Subagent vs Background Agent vs Agent Team

Type	Use when
Subagent	Side task within a single session, return a summary
Background agent	Run many independent full sessions in parallel, monitor from one screen
Agent team	Multiple sessions that coordinate and communicate with each other

---

Cost Tip

Route simple, repetitive tasks (file lookup, search) to Haiku subagents:

---
name: file-finder
description: Find files and search code. Fast lookups only.
model: haiku
tools: [Read, Glob, Grep]
---

Haiku is ~15x cheaper than Opus for the same task.

---

Disabling Subagents

// settings.json — block a specific built-in
{
  "permissions": {
    "deny": ["Agent(type:Explore)"]
  }
}

// Block all subagents
{
  "permissions": {
    "deny": ["Agent"]
  }
}

🧠 Quick Recall

• Trick: “Own window, own tools, reports back once.”

👨‍🏫 Teach It

• Show: test-runner subagent; /context before vs after — main window stays clean.
• They’ll trip on: subagents don’t see your conversation — the spawn prompt must carry full context.

---

Learning path: ⬅ 28-agents-overview.md · Index · ➡ 30-agent-project-structure.md