Agent System (Subagents)

Subagents are specialized Claude instances that handle specific tasks in isolated contexts. They protect your main context window and parallelize independent work.

Built-in Subagents

Agent	Purpose
Explore	Fast read-only codebase search — locating files, symbols, patterns
Plan	Software architecture and implementation planning
claude	General-purpose catch-all
claude-code-guide	Questions about Claude Code itself
statusline-setup	Configure the Claude Code status line

Invoke a Subagent

In a prompt:

@Explore find all files that use the authentication middleware

Or Claude auto-delegates when a task matches the agent’s description.

Create a Custom Subagent

File: .claude/agents/code-reviewer.md

---
name: "code-reviewer"
description: "Reviews code for bugs, security issues, and best practices"
model: "claude-sonnet-4-6"
---

You are an expert code reviewer. Your job:

1. Identify bugs and security vulnerabilities
2. Check for performance problems
3. Suggest best practices and cleaner alternatives
4. Evaluate test coverage

Format each finding as:
- **Issue:** description
- **Severity:** high / medium / low
- **Location:** file:line
- **Fix:** suggested change

User-level agents (all projects):

~/.claude/agents/my-agent.md

Frontmatter Options

---
name: "agent-name"                # identifier used in @mentions and /agents
description: "What it does"       # used to decide when to auto-delegate
model: "claude-opus-4-8"          # model for this agent (can differ from main)
tools:                            # restrict which tools this agent can use
  - Read
  - Grep
  - Bash
disable: false                    # disable this agent
require-approval: false           # ask user before spawning
---

Restrict Agent Tools

---
name: "read-only-researcher"
description: "Research and analysis only — never modifies files"
tools:
  - Read
  - Grep
  - Glob
  - WebSearch
  - WebFetch
---

You research and explain. Never edit, write, or run shell commands.

Manage Agents

/agents                        # view all agents in interactive UI
/agents disable code-reviewer  # disable an agent

Parallel Agent Use

Claude can run multiple subagents in parallel for independent tasks:

I need you to:
1. @Explore — map the entire authentication flow
2. @code-reviewer — review the changes in src/auth/
3. @Plan — design the new OAuth integration

Claude coordinates the work and merges the results.

Worktree Isolation

Subagents can be launched in isolated git worktrees so their file changes don’t interfere with each other:

Create a worktree for this task to avoid conflicts with other work.

Or via the Agent tool’s isolation: "worktree" parameter (used internally).

Block an Agent

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

🧠 Quick Recall

• Trick: “Delegation = context protection.”
• Ladder: main session → subagents → teams → workflows.

👨‍🏫 Teach It

• Do: sketch the ladder on a whiteboard before showing any of it.
• They’ll trip on: parallelizing before decomposing — split the work first.

---

Learning path: ⬅ 27-plugins.md · Index · ➡ 29-subagents.md