Claude Code Claude CodeAgents

Subagents in Claude Code: agent teams that scale

A subagent is a worker Claude Code spins up with its own clean context to handle one bounded piece of a larger job, then reports back. It lets you fan a big task, research fifty accounts, review a batch of drafts, out to many workers at once instead of cramming everything into one session that turns to mush. You keep the main thread lean and get more done in parallel.

Overview

The first time I tried to research fifty target accounts in one Claude Code session, it was crisp for about a dozen. Then it started bleeding: it attributed one company's funding round to another, kept referencing an account we had already finished, and by account thirty the context was a drawer of loose facts from thirty different companies. I did not have a prompting problem. I had a one-desk-for-fifty-people problem.

Subagents are the fix. Instead of one worker holding fifty accounts in their head, you get fifty workers who each hold one, do the research, and hand back a clean result. This is how the same operator goes from researching one account well to researching a whole list well, without the quality falling off a cliff at account twelve.

A subagent is a worker with its own desk

A subagent is a worker with its own desk

A subagent is a separate instance of Claude that the main session hands a single, bounded task to. It gets its own context window, can be given its own tools, does the one job, and returns the result. The main thread, the lead agent, holds the overall goal and stitches the pieces back together.

The mental model that made it click for me: the lead agent is the person running the project, and subagents are the people they hand discrete assignments to. Nobody is trying to hold the whole thing in one head. Each has a clean desk and one folder on it.

How subagents fan out work
01The lead agentholds the goal, splits the work
plans the pieces
02Subagentseach takes one piece, own context
researchdraftscore
03The mergeresults return to the lead
one clean result
One job fans out into many, each with a clean context, then merges. More work done, less clutter in the main thread.
Why one big context turns to mush

Why one big context turns to mush

A context window is finite, and everything in it competes for attention. When you pour fifty accounts into one session, each new account crowds the earlier ones, and the model starts confusing them, mixing details, losing track of what is done. I call it context bleed, and you can watch it happen: the answers get vaguer and the mistakes get more confident.

Subagents solve it structurally, not by hoping a bigger window saves you. Fifty accounts across fifty clean contexts means no bleed, because no single context is holding more than it can keep straight. The lead agent only ever sees the goal and the returned results, so it stays lean too.

This is worth internalizing because it runs against instinct. When output gets worse, the reflex is to write a more elaborate prompt or reach for a bigger model, and neither fixes an overloaded context. The problem is not that the worker is not smart enough, it is that you gave one worker fifty folders. The answer is more desks, not a genius who never forgets.

You can feel the moment it would help. When you notice yourself reminding the session about an account it already covered, or catching it blend two companies together, that is the ceiling of one context announcing itself. The fix is not a sterner prompt, it is more desks. The instinct to push harder on a single overloaded worker is the exact instinct to unlearn.

💡

TipIf a session's answers get vaguer and its mistakes get more confident as it goes, that is context bleed. It is a signal to fan the work out, not to write a better prompt.

Lead agent, subagent, and the main thread

Lead agent, subagent, and the main thread

Keep three roles straight. The main thread is where you sit and give the goal. The lead agent is the main session doing the coordinating: it decides how to split the work and merges what comes back. Subagents are the workers it spawns for the pieces.

The reason this matters is that the merge is where the value lands or leaks. Fifty good account briefs are worthless as fifty scattered outputs; they are gold as one ranked, deduplicated list on the main thread. Delegation buys you parallelism; the merge is what turns it back into something you can act on.

What to delegate, what to keep

What to delegate, what to keep

Delegate work that is bounded and parallel: the same operation repeated across many items, where each item is independent. Research this account. Review this draft. Score this lead. Each subagent needs nothing from the others, so they run at once and none of them bleeds into the rest.

Keep the work that needs one coherent view: the strategy, the judgment calls, and the merge. Deciding which fifteen of the fifty accounts to actually work this quarter is not a delegation task, it is a you task, made easier because fifty clean briefs are sitting in front of you.

  • Good to delegate: per-account research, per-draft review, per-lead scoring, per-competitor teardown.
  • Keep on the main thread: the goal, the prioritization, the final ranking, anything that compares items to each other.
  • Rule of thumb: if the pieces are independent, fan out. If they need to see each other, keep them together.
Custom subagent types

Custom subagent types

Out of the box, a subagent is a general worker. You can do better by defining subagent types with their own standing instructions and their own tool access, so a research subagent and a copywriter subagent behave like the specialists they are. These live as files in your project, the same pattern as CLAUDE.md and custom commands: config that travels with the repo.

This is where a fan-out stops being a blunt instrument. An account-researcher type that knows your ICP and always cites sources, paired with a brief-writer type that knows your voice rules, gives you a small assembly line: one finds the facts, the next turns them into the one-pager, and the lead agent merges. You built a team, and it is a few files.

💡

TipGive each subagent type only the tools it needs. A researcher needs web and CRM read access; it does not need permission to write to your CRM. Narrow tools are a guardrail, not a limitation.

Match the model to the worker

Match the model to the worker

A fan-out is a chance to spend money where it actually matters. The subagents doing bounded, mechanical research do not need your most expensive model; a fast, cheap one is fine because the task is narrow and well-specified. Save the strong model for the lead agent and the merge, where the work is comparing, ranking, and deciding, the part where a smarter model earns its price.

This is the opposite of the nervous default, reaching for the biggest model everywhere because it feels safer. On a fifty-account fan-out, the model choice is the difference between a run that costs a few dollars and one that costs real money, for output that is often indistinguishable on the worker tasks and only meaningfully better on the merge. Cheap workers, expensive judge.

💡

TipCheap model for the workers, strong model for the merge. That single split usually cuts the cost of a big fan-out without touching the quality of the result.

A fan-out, start to finish

A fan-out, start to finish

It is worth walking one all the way through, because the shape repeats for almost any bounded, parallel job. You hand the lead agent a target list and a clear per-item instruction. It reads the list, spins up a researcher per account, and each researcher, in its own clean context, pulls the site, checks the CRM history, scores fit, and writes back a short, cited brief. None of them can see the others, which is exactly why none of them bleeds.

Then the merge. The lead agent collects the fifty briefs and turns them into one artifact you can act on: a single file, ranked by fit, deduplicated, with the weak-source ones flagged for a look. What took an afternoon per handful now takes a coffee break for the whole list, and the fiftieth brief is as sharp as the first because the fiftieth account had a desk to itself. That is the entire value, and it lives in the split between the fan-out and the merge.

Where it goes wrong

Where it goes wrong

The big one is over-delegation: fanning out work that actually needed one context. If you split a task whose pieces depend on each other, each subagent guesses at the parts it cannot see, and you spend more time reconciling contradictions than you saved. Parallelism is only free when the pieces are truly independent.

The other is trusting the fan-out blindly. Fifty subagents can return fifty confidently-wrong briefs as easily as fifty good ones. The merge step is also your review step: skim for the account that clearly got bad source data before you act on the list, the same way you would spot-check a report a new analyst handed you.

  • Over-delegating work whose pieces needed to see each other.
  • No review at the merge, so a few bad briefs slip into the list you act on.
  • Giving every subagent write access when it only needed to read.
  • Fanning out a job small enough that one session would have been faster than the coordination overhead.
The GTM version: fan out the target list

The GTM version: fan out the target list

Here is the play that changed how I work. I hand Claude Code a CSV of the quarter's target accounts and one instruction: for each account, research the company, score fit against our ICP, and write a one-line angle and two risks. It fans out a subagent per account, each with a clean context, and merges the results into a ranked file.

What used to be an afternoon per handful of accounts becomes a coffee break for the whole list, and the quality holds at account fifty because account fifty had a desk to itself. Then the part that is actually mine, deciding where to spend the week, happens over a clean, ranked brief instead of a blank page. Where would you point the first fan-out on your own list?

How to set it up

How to set it up

Open the subagents manager

Claude Code manages subagent types through a command. Open it to see what is defined and to create a new type.

claude
$/agents
No custom subagents yet. Create one? (name, description, tools, model)
$

Define a specialist type

Give the type a job, standing instructions, and only the tools it needs. An account-researcher that knows your ICP and cites its sources:

"You research a single B2B account for our outbound. Read the company's site and any CRM history, then return: fit against our ICP (VP of Marketing at B2B SaaS, 50 to 500 employees), a one-line angle, and two deal risks. Always cite where each fact came from. Read-only: web and CRM. Never write to the CRM."

💡

TipOne narrow type per job beats one do-everything worker. A researcher and a brief-writer that each do one thing are easier to trust and reuse.

Fan a real job out to it

Point the lead agent at the whole list and let it spawn a subagent per item. Each runs in its own context, so the fiftieth account is as sharp as the first:

claude
$Use the account-researcher subagent on every row in accounts.csv, then merge the results into a ranked brief in fit order.
Spawning 42 researchers ... merging ... wrote accounts_ranked.md (best fit first).
$

Review at the merge

The merge is also your QA. Skim the ranked output for anything that clearly got bad source data before you act on it, the way you would spot-check a batch a new analyst handed you. Then make the call the fan-out set up for you: where to spend the week.

FAQ

Frequently asked questions

What exactly is a subagent?

A separate instance of Claude that your main Claude Code session hands one bounded task to, with its own context and tools. It does the job and returns the result, while the main session coordinates and merges.

Why not just use one big session with a large context?

Because a single context degrades as it fills. Pour fifty accounts into one session and it starts confusing them. Many small contexts each stay sharp, which is the point of fanning out.

When should I not use subagents?

When the pieces of the work depend on each other. If each subagent would have to guess at parts it cannot see, keep the work in one context. Subagents are for independent, parallel pieces.

How do I create a custom subagent?

Run /agents in Claude Code and define a type: its job, its standing instructions, its tools, and its model. Save it in the project so it travels with the repo.

Can subagents write to my CRM or send email?

Only if you give them tools that can, and you should be deliberate about it. Give a researcher read-only access; keep write and send actions on types you trust and behind approval.

Do subagents cost more?

Running many workers uses more tokens than one session, but it does work one session cannot do well at scale. Use a cheaper model for the fan-out workers and a stronger one for the merge to keep the bill sane.

How is this different from routines or Dispatch?

Subagents fan out within a single job you are running now. Routines and Dispatch are about running Claude on a schedule or unattended. You can combine them: a routine that fans out to subagents every Monday morning.

What is the first GTM job to try this on?

Account research across a target list. It is bounded, parallel, and exactly the kind of work that falls apart in one session and shines across many.

Sources

Sources & further reading

Claude ships fast. This page was last reviewed Aug 22, 2026; verify time-sensitive details against the official docs above before relying on them.

Get the AI-for-GTM playbook in your inbox

New Claude guides, use cases, and prompts every couple of weeks.

Subscribe →