Subagents

A subagent is a specialist with its own context window, its own instructions and its own tool permissions. It goes off, does the noisy work, and brings back a summary. Your main conversation stays clean.

I send a smaller frog. He comes back with a summary.

Facts checkedNov 11at the source

Make one

Run /agents, or simply ask Claude to write one for you.
Or create the file yourself. .claude/agents/ for this project, ~/.claude/agents/ for all of them.
Describe when to use it. name and description are required. Claude reads the description to decide when to hand work over.

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
Your system prompt goes here.

The ones already built in

ExploreFast, read-only codebase search
PlanResearch during plan mode
General-purposeMulti-step tasks that need both looking and doing

Subagent or main conversation?

Use a subagent for	Stay in the main conversation for
Work that produces a lot of output, like test runs and logs	Back-and-forth where you steer as you go
Jobs that need tighter tool restrictions	Phases that share a lot of context
Self-contained work that can return a summary	Quick, targeted edits and anything where waiting matters

The fine print

A subagent does not see your conversation history. Tell it what it needs.
Up to 20 run at once by default, nested up to 3 deep.
If two share a name, project beats user, and user beats plugin.
Optional fields include tools, model, permissionMode, maxTurns, skills and mcpServers.

Clodhopper move: Spawning nine subagents to rename a variable. Each one starts from zero and reads the codebase again. That is nine frogs learning the same pond.

Source: the Claude Code documentation at code.claude.com/docs, read on November 11, 2026.