Subagents — Delegating Work to Focused Helpers

One Brain Can Only Hold So Much

When Claude Code works on a task, it keeps everything in its working memory: your instructions, the files it has read, the search results, the errors it hit, the conversation so far. This memory is called the context window, and it's finite. On a big task — "search the whole codebase for every place we send emails, then summarize how it works" — that memory fills up fast with raw file dumps, and the important stuff gets crowded out.

Subagents solve this. A subagent is a separate helper that Claude can hand a focused job to. The helper does the work in its own memory, then reports back just the answer. The messy details never clog up your main session. Think of it as a manager delegating a research task to an assistant: you get the one-page summary, not the assistant's entire pile of notes.

---

The Big Win: Context Isolation

This is the key idea, so let's make it concrete.

Imagine you ask Claude to "find out how authentication works in this app." Without a subagent, Claude reads twenty files into its own memory to figure it out. Now those twenty files are sitting in the context window for the rest of your session, taking up space and distracting from your next request.

With a subagent, Claude says to a helper: "Go figure out how authentication works." The helper opens those twenty files in its own separate memory, works it out, and hands back a clean three-paragraph summary. Your main session only ever sees the summary. The twenty files of raw code never touched it.

That's context isolation. The subagent's working mess stays in the subagent. The benefits:

• More room in your main session for the actual work.
• Sharper answers, because the main conversation isn't buried in noise.
• Cheaper, because you're not carrying thousands of lines of irrelevant code around.

---

Defining a Subagent

A subagent is a Markdown file, just like the other tools in this module. It lives in:

The file has frontmatter describing the helper, then a body that acts as its instructions (its "job description"). Here's a code reviewer:

---
name: code-reviewer
description: Reviews recent code changes for bugs, security issues, and broken
  functionality. Use after a feature is built, before committing.
tools: Read, Grep, Bash
model: sonnet
---

You are a focused code reviewer. When given a task:

1. Look at the recent changes.
2. Check for bugs, logic errors, and anything that could break existing features.
3. Flag security problems — exposed secrets, missing validation.
4. Return a short, prioritized list. Be direct. No filler praise.

Do not fix anything. Only report what you find.

The frontmatter fields:

• name — what you call the subagent.
• description — what it's for and when to use it. This is how Claude decides to delegate to it, so write it clearly.
• tools (optional) — which tools the helper is allowed to use. Leave it out and the subagent can use everything; list specific tools to keep it focused. (A reviewer that only reads and searches doesn't need permission to write files.)
• model (optional) — which Claude model the helper runs on. You might use a faster, cheaper model for simple lookups.

The body below the frontmatter is the subagent's standing instructions — its personality and rules.

---

When to Delegate

Subagents aren't for everything. Reach for one when a task is:

• Big and self-contained — "research how X works across the whole codebase," "audit every form for missing validation." The kind of thing that reads a lot but reports a little.
• Repetitive and specialized — code review, writing tests, summarizing logs. Bundle the expertise once, reuse it forever.
• Noisy — anything that would dump a mountain of raw output into your session. Let the subagent absorb the mess and hand back the conclusion.

Don't bother for small, quick tasks. If you just want Claude to fix one line, delegating is overhead. The sweet spot is "go away, do a chunk of focused work, come back with a clean result."

---

How Delegation Happens

There are two ways a subagent gets used.

Automatically. If a subagent's description matches what you're asking for, Claude will delegate to it on its own. Ask "can you review the changes I just made?" and Claude notices the code-reviewer description fits, and hands off the job.

Explicitly. You can also just name it:

"Use the code-reviewer agent to check my recent changes."

Explicit is more reliable when you specifically want a certain helper. There's also an /agents command that lets you see your subagents and set new ones up interactively, generating a first draft for you.

---

Running Helpers in Parallel

Here's where it gets genuinely powerful. Because each subagent works in its own separate memory, Claude can run several at once — like assigning tasks to a few assistants who all work simultaneously.

Suppose you say:

"I'm about to ship. Check three things at the same time: review my code changes, audit the app for security issues, and confirm the tests still describe the right behavior."

Claude can fire off three subagents in parallel — one per task. Each works independently in its own context, and Claude collects all three reports. What might have taken three sequential passes finishes in roughly the time of one. For big pre-launch checks or multi-angle research, parallel subagents are a serious time-saver.

---

Summary

• A subagent is a focused helper Claude delegates a self-contained task to; it works in its own separate memory and reports back only the result.
• The core benefit is context isolation — the subagent's raw working mess (files read, search noise) stays out of your main session, keeping it clean, sharp, and cheaper.
• Define one as a Markdown file in .claude/agents/ (project) or ~/.claude/agents/ (global), with frontmatter: name, description, and optionally tools and model.
• Delegate for big, self-contained, repetitive, or noisy work — not for quick one-line fixes.
• Claude delegates automatically when a subagent's description fits, or explicitly when you name it. The /agents command helps you create them.
• Because each runs in isolation, Claude can run multiple subagents in parallel — great for multi-angle reviews and research.