Subagents 101: Giving Claude a Team to Work With

Claude Code can search code, query a sample database, review changes, and write documentation. This post is about what happens when those tasks are split across several focused agents instead of one conversation.

---

The Problem With One Context Window

Every message you send to Claude includes the full conversation history — everything said, every file read, every MCP response returned. A long session gets expensive fast, and the more Claude has to carry, the more likely it is to lose track of earlier context.

Here’s a concrete example. You ask Claude to investigate a flaky test:

1. Claude reads 40 log files — 20,000 tokens consumed
2. Claude greps for error patterns — another 5,000 tokens
3. Claude reads 10 relevant source files — 10,000 tokens
4. Claude summarises the findings — 500 tokens

After all that, your conversation is 35,500 tokens heavier. Every subsequent message carries that weight. Run a few investigations like this in one session and you’re heading for compaction.

Now imagine Claude could delegate that investigation to a helper — one that does all the work in its own space and returns only the summary. Your conversation gets 500 tokens heavier, not 35,500. That’s what subagents do.

---

What Is a Subagent?

A subagent is a separate Claude instance that Claude spawns to handle a specific task. It has its own context window, its own tools, and its own system prompt. When it finishes, it returns a summary back to the parent — and then its context is thrown away.

The mental model: a separate research notebook. A subagent explores a question in its own space and returns the result, without bringing every note and dead end into your main conversation.

This gives you three things:

Context isolation. Whatever the subagent reads, greps, or runs doesn’t pollute your main conversation. A subagent can process 50,000 tokens of output and return 300 tokens of findings.

Specialisation. You can give a subagent a restricted set of tools. A code reviewer that can only read files. A database agent that can only run SELECT queries. A subagent can’t accidentally do things it shouldn’t.

Parallelism. Claude can spawn multiple subagents at once for independent tasks. Three subagents researching three different theories simultaneously, each in their own context.

---

The Built-In Subagents

Claude Code ships with a few subagents out of the box. You’ve probably already been using them without realising it.

Explore — when Claude needs to search or analyse code, it often delegates to the Explore subagent. It runs on Haiku (the fastest, cheapest model) and only has read access — no Write or Edit tools. This is why exploring a large codebase can feel fast: it’s Haiku doing read-only work in a separate context, not Sonnet chewing through it in your main window.

Plan — when you use plan mode, Claude delegates research to the Plan subagent. It gathers information without being able to implement anything, then surfaces a plan for you to approve.

General-purpose — handles complex multi-step tasks that need both exploration and modification. Inherits the parent’s model and tools.

There’s also a Claude Code Guide subagent for answering questions about Claude Code features — that’s what’s running when you ask “how do I do X in Claude Code?”.

---

Custom Subagents

The more interesting part is creating your own. A custom subagent is a markdown file with a YAML frontmatter block. Store them at the project level (.claude/agents/) for one repository, or globally (~/.claude/agents/) for your personal projects.

Here’s a minimal example — a read-only code reviewer:

---
name: code-reviewer
description: Review code changes for quality, correctness, and potential issues
tools: Read, Grep, Glob, Bash
---
You are a careful code reviewer. Look for correctness issues, security problems, and unclear code. Be specific — point to exact lines. Don't approve changes you're not confident about.

Two things matter here:

• description is how Claude decides when to delegate to this agent. Write it as “when to use this” — Claude reads it and routes tasks accordingly.
• The markdown body is the system prompt. This is where you give the subagent its expertise and constraints.

Save that file, and next time you ask Claude to review code, it may delegate automatically. Or you can @-mention it directly: @"code-reviewer (agent)" check these parser changes.

---

When to Use Subagents

Good fits:

• Heavy exploration tasks. “Search the entire codebase for all usages of this pattern and summarise them.” Delegate to Explore, get a clean summary back.
• Constrained access. You want Claude to query a sample SQLite database but not write to it. Build a db-reader subagent with only Bash access and a hook that blocks non-SELECT commands.
• Parallel research. “Investigate three approaches simultaneously.” Spawn three subagents, each working on one theory.
• Reusable specialists. A security auditor, a test runner, a docs writer — define once, use on every project.

Not worth it:

• Quick one-off questions. The overhead of spawning a subagent (a few thousand tokens to set up) isn’t worth it for a 10-token answer.
• Tight iterative loops. If you’re going back and forth refining something, stay in the main conversation — subagents are stateless, each invocation starts fresh.
• Tasks that need your full context. A subagent doesn’t see your conversation history, only the prompt you give it. If the task depends on everything discussed so far, keep it in the main thread.

---

The Isolation Trade-Off

Subagents don’t have access to your conversation history. They get the prompt you give them and nothing else.

This is a feature — it keeps their context clean. But it’s also a trap if you forget about it. If a subagent needs to know a constraint you discussed earlier, you have to include it explicitly in the spawn prompt. A subagent you delegate a review to doesn’t know “this module must be stateless” unless you tell it.

The other thing to know: subagents cannot spawn other subagents. If your workflow needs nested delegation, you’ll need to chain it from the main conversation instead.

---

Worktrees: Parallel Work Without Conflicts

One advanced pattern worth knowing: worktree isolation. When you set isolation: worktree in a subagent’s frontmatter, Claude creates a separate git worktree for that agent — a full copy of the repo in its own directory.

This means two subagents can edit different files in the same repo without stepping on each other. No git conflicts. When the subagent finishes (or if it makes no changes), the worktree is cleaned up automatically.

---
name: refactor-parser
description: Refactor the parser module in an isolated worktree
isolation: worktree
tools: Read, Edit, Bash
---
Refactor the parser module. Focus on reducing duplication and improving error handling.

This is most useful when you’re doing risky or experimental work you might want to discard, or when you’re running multiple long-running changes in parallel.

---

Controlling Costs

Since subagents are separate Claude instances, each one has its own token cost. A few ways to keep that under control:

Route to cheaper models. The model field in frontmatter lets you specify which model a subagent uses. A research agent that only needs to read and summarise files? Use Haiku — it’s 3-5x cheaper than Sonnet and plenty capable for read-only work.

---
name: codebase-explorer
description: Explore and summarise patterns in the codebase
model: haiku
tools: Read, Grep, Glob
---

Right-size the task. Don’t spawn a subagent for a 10-line file read. The setup overhead (~1-3K tokens) isn’t worth it. Subagents pay for themselves on longer, more complex tasks.

Use background for long-running work. You can spawn a subagent with background: true and it’ll run while you keep working. Useful for “run the full test suite while I implement the next feature” — but be aware the result is lost if the parent session crashes.

---

Setting Up Your First Subagent

The easiest way is through the /agents command. Open it, choose your scope (project or personal), and Claude will walk you through generating the frontmatter and system prompt based on what you describe.

If you’d rather write it manually: create a .md file in .claude/agents/ (for project scope) or ~/.claude/agents/ (personal), fill in the frontmatter, and write the system prompt in the body.

For a personal project, start with a code-reviewer subagent that can read the repository and explain potential issues. Keep its instructions focused on that project’s conventions.

---

Quick Reference