How it works: Subagents

Subagents: Claude handing work to more Claudes

A subagent is a second Claude that the one you are talking to starts for a single job. It gets a written brief, works in its own fresh context window, and hands back a short report.

The problems they solve

Big reading jobs flood the conversation. Answering one question well can mean reading 40 web pages. Done in your conversation, all of that sits in the context window, crowds out what you said earlier, and gets summarised away. A subagent reads them in its own window, and your conversation only sees the page of findings it hands back.

Claude grades its own work generously. The Claude that wrote a draft knows what it meant, so it reads straight past the gaps. A subagent that gets only the draft and the brief reads it the way a stranger would. That is why review-writing gives each writing rule its own fresh reviewer.

One conversation does one thing at a time. Three subagents can compare three laptops at once, in the background, while you keep talking about something else.

Easy work doesn't need the strongest model. A subagent can run on a cheaper, faster model for a lookup or a summary, so the heavy model and your plan's allowance go to the conversation that needs them (picking a model, below).

A job that only reads shouldn't be able to change anything. An agent file lists the tools a subagent may use; the pack's researcher can read the web and write its notes, and nothing else.

The cost: a subagent knows only what its brief says, none of your conversation. Ask for one the way you would brief a person: what you want back, what you already know, and what to skip.

When to use one

Reach for one when a job is big and separate from the conversation: research, reading a long document, checking a draft with fresh eyes, or several independent questions at once. Just ask:

Use a subagent to find out how Roth IRA contribution limits work this year.

Use three subagents in parallel to compare these three laptops on battery life, weight, and price.

Subagents usually run in the background, so you can keep talking while they work, and Claude tells you when each one finishes. Press Ctrl+B to send a long-running one to the background yourself.

Picking a model

Each subagent can run on a different model, and the cheaper ones leave more of your plan for the conversation that matters:

• haiku: fastest and cheapest. Good for simple lookups, sorting, and summarising.
• sonnet: the everyday choice for research and most work.
• opus and fable: the strongest, for hard reasoning, a careful review, or tricky writing, where your plan includes them; /model lists what yours has.

Say it in the request ("use a haiku subagent to list every PDF in my Downloads") or pin it in an agent file, below.

Agent files

Claude Code ships a few general subagents. You can add your own as files in ~/.claude/agents/, each one a job description: a name, when to use it, which model, which tools it may use, and its instructions. This pack always installs one, ~/.claude/agents/researcher.md:

---
name: researcher
description: Looks a question up on the web in trustworthy sources and writes the findings, with a link for every claim, to a Markdown file. Use for facts, comparisons, prices, how-tos, and anything that has to be checked against a source.
model: sonnet
tools: Read, Write, Grep, Glob, WebFetch, WebSearch
---

You answer one question from sources and say where each fact came from.
...

Claude picks it on its own when a request fits the description. To make sure it runs, name it ("use the researcher agent to ...") or type @agent-researcher and your question. tools keeps it to reading the web and writing its notes, so it can't change anything else. To make another, ask Claude: "make me a reviewer agent on opus that reads my drafts and lists what a stranger would find confusing." Edit the file afterwards like any other; model takes haiku, sonnet, opus, fable, or inherit (whatever the main conversation uses).

A subagent's report sounds as confident when it is wrong as when it is right. For anything you will act on, ask Claude to check the sources it cites, or open the links yourself.

The engineering workflow

For people who build software, the optional workflow part adds four more agents next to researcher (scout finds things in a codebase, planner designs a change, builder implements one with tests, reviewer hunts for bugs), two skills (delegate, the playbook for splitting a job across them, and headless-review, a multi-reviewer check of a branch that makes about a dozen separate Claude calls, so it suits a large change), and a set of rules about commits, branches, worktrees, testing, and code style in ~/.claude/rules/leaven/. The git and delegation rules load in every session and the coding ones only when Claude touches code. The rules and agent instructions tell Claude not to push or open pull requests unless you ask, which is instruction, not a lock. builder's output gets a reviewer agent's look before Claude reports it.

Use the delegate skill to split this refactor across agents.

The agents pin haiku or sonnet, which every plan has, and planner follows whatever model your session runs. See setup for engineers.

Research, three ways

• Ask in the conversation: "what's the best way to get a refund from an airline in the EU?" Claude searches and answers right there. Fine for quick questions.
• /mattpocock-skills:research: for a question worth keeping. It hands the reading to a background agent and saves the findings, with sources, as a Markdown file in the folder.
• The researcher agent: the same idea as a reusable agent file you can change, such as pointing it at the sources you trust or switching its model.