Today we'll look at subagents in Claude Code: helpers that take on a side task in their own context window and hand back only a summary.

When Claude has to dig through search results, logs, or a pile of files we won't look at again, a subagent does that work somewhere else. Our main conversation stays clean, and we only get the answer.

Let's dive in.

The Built-in Ones

Claude Code ships with a few subagents that Claude uses on its own when they fit:

• Explore is a fast, read-only agent for searching and understanding a codebase. Write and Edit are denied.
• Plan does read-only research while we're in plan mode, so exploration output stays out of the main thread.
• general-purpose gets every tool available to subagents, for tasks that need both exploring and changing things.

We don't have to do anything to use them. When Claude needs to find where something lives, it hands that off to Explore and keeps working with the result.

Writing Our Own

A custom subagent is a Markdown file with YAML frontmatter. The body becomes its system prompt:

---
name: data-reviewer
description: Reviews code for quality and security. Use proactively after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are Data, a meticulous code reviewer. For each issue,
explain the problem, show the current code, and suggest a fix.

Only name and description are required. The filename doesn't have to match the name.

Where we save it decides who gets it:

# Project: commit it so the whole team gets it
.claude/agents/data-reviewer.md

# User: follows us into every project
~/.claude/agents/data-reviewer.md

We can also ask Claude to write the file for us. It knows the format.

Tools and Models

The tools field is an allowlist. Leave it out and the subagent inherits every tool available to subagents. To go the other way, disallowedTools removes tools from whatever it would get:

---
name: hal-researcher
description: Researches the codebase without changing it
disallowedTools: Write, Edit, mcp__github
---

That one keeps Bash and every other tool, minus file writes and the github MCP server.

The model field takes sonnet, opus, haiku, fable, a full model ID, or inherit. Routing a high-volume job to haiku is a nice way to keep costs down.

Calling Them

Claude decides when to delegate based on each subagent's description, so a clear one matters. Phrases like "use proactively" encourage it to delegate on its own.

We can also be explicit. Naming the agent in a prompt usually works, and an @-mention guarantees it:

Use the data-reviewer subagent to check my last commit
@agent-data-reviewer look at the auth changes

Or we can run the whole session as that agent, with its tools and model:

claude --agent data-reviewer

Setting "agent": "data-reviewer" in .claude/settings.json makes it the default for the project. Neat!

Watch Out

Frontmatter field names are camelCase and must match exactly. A typo like disallowed-tools is ignored without an error, so the subagent quietly gets more tools than we meant.

If ~/.claude/agents/ didn't exist when the session started, a newly created agent won't show up until we restart Claude Code. Edits to existing agent files are picked up within a few seconds.

To keep Claude from using a particular subagent, deny it like any other tool:

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

More info about subagents can be found at the Claude Code docs.