Deep dive · side channel

Subagents

A helper that splits off inside your session, does the muddy work in its own memory, and rejoins the main channel carrying only the clear answer.

The problem this solves

A session is one conversation with a finite working memory, and most of what Claude reads is disposable — you need the three failing tests, not the four thousand lines printed on the way to finding them. Left in the conversation, the noise crowds out the work you care about.

A subagent is Claude handing that side task to a helper with its own memory. The helper reads and sifts there, then returns a summary: your conversation gets the conclusion, never the noise. It's also a specialist you define once and reuse — a small file setting its instructions, tools, and model that the whole team can share.

You'll recognize the situation

The test run that eats the afternoon's conversation

A developer is deep in a productive session and needs the test suite run — which prints thousands of lines. Paste that in, and the session's memory of the feature work drowns in stack traces.

With a subagent, the ask is one line — straight from the docs:

Use a subagent to run the test suite and report only the failing tests
with their error messages

The noise stays in the helper's memory; the conversation gets a short list of failures. The docs call isolating high-volume work — test runs, doc fetching, log processing — one of the most effective uses of subagents.

The analyst who should query the warehouse but never write to it

A data team wants Claude answering questions against the warehouse — but the platform lead fears the stray write more than any query.

The docs' worked example is a db-reader subagent: a check inspects every command before it runs, letting read-queries through and blocking anything that would write. The guardrail lives in a file the team can review and version, not in a prompt someone hopes the model follows.

Three unfamiliar corners of the codebase, one afternoon

Someone new to a codebase — or scoping a risky change — needs to understand three subsystems that don't depend on each other.

Research the authentication, database, and API modules in parallel
using separate subagents

Each helper explores its area independently and Claude pulls the findings together. The conversation ends holding three digests instead of three raw expeditions.

Shoal water — don't use this when

The docs are direct about when the main conversation is the better channel:

The task needs back-and-forth. Steering belongs in the conversation, not across a hand-off.
The phases share context. When planning, building, and testing build on the same understanding, splitting them wastes it.
It's a quick, targeted change. Not worth the hand-off.
Speed matters. A subagent starts fresh, so it spends time getting oriented first.

Talk track — say it to a customer

"Claude's conversation has a finite working memory. A subagent does the noisy side work — test runs, log digs, doc fetches — in its own memory, and hands back only the answer."

"You define a specialist once — its instructions, its tools, its model — check the file into the repo, and the whole team delegates to the same reviewer or debugger."

"It's contained by design: a subagent has only the tools you grant it, and anything that needs a permission still asks the developer."

If the customer asks…

"Does this cost more?": It's the lower-cost way to parallelize: results come back summarized, and routine helper work can run on a cheaper model (the docs suggest Haiku). One caveat: many helpers each returning detailed results still add up.
"Who approves what a subagent does?": The developer. When a helper hits an action that needs approval, the prompt appears in the developer's session, naming which helper is asking — and a definition can restrict it up front with a short tool list or read-only access.
"Is this stable, or an experiment?": Stable. Built-in subagents ship with Claude Code and Claude already uses them automatically. Unlike agent teams (experimental) or agent view (research preview), the docs attach no such caveat here.
"How does the team share these?": A subagent is a small text file. In the project's .claude/agents/ folder it ships with the repo; in the developer's home folder it follows them across projects.

See it work

A subagent is a text file with a short header. This is the docs' code-reviewer, abridged — enough to demo the whole idea:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for
  quality, security, and maintainability. Use immediately after writing
  or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality
and security. When invoked: run git diff to see recent changes, focus on
modified files, and begin review immediately. Provide feedback organized
by priority: critical issues, warnings, suggestions.

The description tells Claude when to delegate; the tool list is what it may touch (no editing tools — this reviewer can't change code). Easiest way to make one: ask Claude to write it.

The two-minute demo

Ask in plain language — Claude delegates:

Have the code-reviewer subagent look at my recent changes

Or guarantee it runs by @-mentioning it, like a file:

@agent-code-reviewer look at the auth changes

Or run a whole session as the specialist:

claude --agent code-reviewer

Helpers usually run in the background while you keep working; results arrive when they finish. Everything deeper is in the full reference.

Where the river forks

Several whole tasks, not one side task?

Hand each off as a background session, watched from agent view.

Agent view →

More workers than a conversation can juggle?

Move the plan into a script.

Dynamic workflows →

Workers that should debate each other?

Subagents report back; they don't confer. That's the agent-teams experiment.

Agent teams →