Subagents: parallel research without the mess

Research is messy. Thirty tabs, half-read pages, three dead ends. When Claude does that kind of digging in your main conversation, all the mess lands in its context, the working memory it has for the session. By the third company you asked about, it's wading through pages from the first two.

Subagents fix that. You hand each messy job to a helper with its own clean workspace, and only the result comes back.

What a subagent is

A subagent is a separate Claude worker that your main conversation hands a task to. It gets:

its own context window, so its reading and searching never touch yours
its own instructions (a system prompt you write)
its own tool list, so a researcher can be blocked from editing your files
optionally its own model, so routine jobs can run on a cheaper one

It does the work, then returns a summary. Anthropic's docs put the use case plainly: reach for one when a side task would flood your main conversation with search results, logs or file contents you won't look at again.

Three things follow from that. Your main conversation stays focused. Independent jobs can run at the same time. And you can give each kind of job tighter limits than you'd give Claude in general. The catch: every subagent uses its own tokens, which count toward the same usage limits as your main conversation. Ten researchers cost roughly what ten separate conversations cost.

The built-in ones

Claude Code ships with subagents it uses on its own:

Explore: fast, read-only searching and reading of your files
Plan: gathers context while you're in plan mode
general-purpose: multi-step jobs that need both research and action

You've probably seen them in your transcript without asking for them. Recent versions can also start a fork, a subagent that inherits your whole conversation so far, and you can start one yourself with /subtask followed by the task.

Where subagent files live

A custom subagent is a Markdown file with a short header (YAML frontmatter) followed by its instructions.

Location	Available in
`.claude/agents/`	This project. Commit it to share with collaborators
`~/.claude/agents/`	All your projects

Plugins can ship subagents too, and if two share a name, the project one wins over your personal one. The frontmatter fields you'll actually use:

name (required): a unique ID like company-researcher
description (required): when Claude should use it. This is what Claude reads to decide
tools: which tools it may use. Leave it out and it inherits everything available
model: sonnet, opus, haiku, fable, a full model ID, or inherit
maxTurns: a cap on how many steps it takes before stopping

There are more (disallowedTools, permissionMode, skills, mcpServers, memory, effort and others). Spell them exactly: Claude Code silently ignores a field it doesn't recognize.

The easiest way to create one is to ask Claude to write it for you, then read the file. The /agents command now just reminds you of that; older versions opened a wizard. If you create the very first file in a new agents folder, restart Claude Code so it notices the folder.

How Claude picks a subagent

Claude reads each subagent's description and matches it against your request. Write descriptions like a job posting: what it does and when to use it. Adding "use proactively" nudges Claude to delegate without being asked.

To be sure a specific subagent runs, name it ("use the company-researcher subagent to...") or type @ and pick it from the list. To run a whole session as one subagent, start with claude --agent company-researcher.

Worked example: research ten leads in parallel

The setup: a leads.csv with ten companies and their websites. The goal: one brief per company, all in the same shape, ready for you to write personal outreach from.

The subagent

.claude/agents/company-researcher.md

---
name: company-researcher
description: Researches one company from public sources and writes a brief using the fixed lead template. Use for any lead or company research, one company per run.
tools: WebSearch, WebFetch, Read, Write
model: sonnet
maxTurns: 25
---

You research one company and write one file.

Use only public, business-level sources: the company's own site, press
releases, job posts, public interviews. Never collect personal contact
details, home addresses, or anything behind a login.

Steps:
1. Take the company name and website from your task.
2. Read 3 to 8 sources. Prefer the company's own pages.
3. Write research/leads/<company-slug>.md using the template below
   exactly. Keep every heading, in this order. If you can't find
   something, write "Not found". Never guess.
4. Reply with one line only: the file path and your confidence
   (high, medium or low).

Template:

# <Company name>

- Website:
- What they sell (one sentence):
- Who they sell to:
- Size signal (team size, funding, or "Not found"):
- Researched on: <YYYY-MM-DD>

## Recent news (last 6 months)
- <item> (<source URL>)

## Likely priorities
- <inference> (based on <source URL>)

## Fit with our offer
<Two or three sentences. Say "weak fit" plainly when it is.>

## Opening line idea
<One sentence that refers to something specific and public.>

## Sources
- <URL>

The prompt

Read leads.csv. For each of the ten companies, start a company-researcher subagent, one company each, all in parallel. When they've all finished, check that every file in research/leads/ has all the template headings and fix any that don't. Then write research/leads/SUMMARY.md: a table of company, fit (strong, medium or weak) and confidence, sorted by fit.

Here's what happens. Claude starts ten researchers in the background (by default up to 20 can run at once). Each searches, reads and writes its file. If one needs a permission, the prompt appears in your main session with the subagent's name on it. Your main conversation only ever sees ten one-line replies, not eighty web pages, so it has plenty of room left to build the summary and, later, draft your emails.

Fewer prompts, safely

Ten researchers fetching pages from dozens of sites means a lot of web-fetch prompts in Manual mode. Either run this in auto mode, or give this research project its own rules:

.claude/settings.json

{
  "permissions": {
    "allow": ["WebSearch", "WebFetch", "Edit(/research/**)"]
  }
}

Allowing every fetch is a real trade-off: a web page can contain instructions aimed at Claude (prompt injection). Keep this folder free of secrets and customer data, and don't connect tools that send email or spend money in the same project. The permissions post goes deeper.

Keep the outputs consistent

Ten parallel workers will drift unless you make drifting hard.

Put a fixed template in the instructions. Say "exactly", list the headings in order, and require "Not found" over skipping a section. Gaps you can see beat gaps that are papered over.
Write to files, reply in one line. Anthropic warns that many subagents returning detailed results can eat your main context. Files keep the detail; the one-liner keeps your session clean.
Pin the model. Same model, same tone. sonnet keeps a ten-company run cheaper than your main model might.
Cap the effort. maxTurns stops a researcher that goes down a rabbit hole. Claude Code marks its output as partial, so you know which ones to check.
Demand a source for every claim. The template asks for a URL beside each news item and inference. Spot-check a few.
Check the shape automatically. The prompt above has Claude verify the headings. For a check that runs every time, a SubagentStop hook can do it; see hooks, or how to give an agent taste.
Test on two before you run ten. Fix the template on a small batch, then scale up.

To measure quality over time rather than eyeballing it, see evals for the rest of us.

When not to use subagents

Use your main conversation when the work needs lots of back and forth, when every step depends on the last, or for a quick edit. A fresh subagent starts from zero and takes time to get its bearings. And watch the bill: parallel is faster, not cheaper. Keeping agents cheap and safe covers spending limits.

One last caution for this example in particular. Research is the easy part of outreach. If these briefs turn into cold emails, follow the rules where you and your leads are (CAN-SPAM in the US, GDPR in the EU), stick to public business information, honor every opt-out, and read each email before it goes.