Sub-Agents, Background Agents, and Agent Teams (Oh My!)
One agent isn't always enough. Claude Code ships with three ways to spawn more: sub-agents, background agents, and agent teams. Once you can compose them, six agents running from a single prompt becomes the new normal. This is the architecture that unlocks the rest of the workshop.
- A working mental model for the three ways Claude Code lets you spawn more agents (sub-agent, background agent, agent team), the four levers you control on each, and how they differ.
- Five named patterns for composing them (Worker Swarm, Research Swarm, Hive Mind 2-Tier, Hive Mind 3-Tier, Patchwork) from Hunter's merge-2-main, plus the Opus/Sonnet/Haiku tier hierarchy that makes them cheap to run.
- A starter prompt that spawns a Research Swarm so you can feel the parallelism the first time, not just read about it.
Try a Research Swarm.
The fastest way to feel sub-agents work is to spawn one. Hand this prompt to Claude and watch three agents run in parallel.
How this fits in the OS.
Claude Code installed and a working main agent. No extra tools, no new credentials. The architecture ships in the box.
Claude's built-in sub-agents (Explore, Plan, general-purpose), custom sub-agents you define in ~/.claude/agents/, and Hunter's merge-2-main patterns for composing them.
Parallel research swarms, hierarchical agent teams that protect your context window, model pinning for cost control, two-stage self-verification, and overnight autonomous work.
Why this matters.
There comes a moment in every Claude Code session where one agent isn't enough. You're researching a topic and want three angles in parallel. You're processing a long document and want to split it into chunks. You're building something and need a writer, a tester, and an architect all working at once. That moment is what this card is about.
The trick that unlocks all of it is the same one that unlocked the rest of agent-native operating: you don't do the parallel work, your agent does. You prompt one agent, and it spawns the others.
Sub-agents are the architecture that unlocks the rest of agent-native work. Skip the concept and the patterns that come later read as magic. Land it and everything from multi-agent research swarms to overnight autonomous pipelines clicks into place.
The three ways to spawn more agents.
Claude Code ships with three ways to spawn agents alongside your main thread. All three are documented in Anthropic's official sub-agent docs. The vocabulary in this card matches theirs.
Sub-agent
A spawned copy of the main agent. Specialized purpose, runs in its own working memory (its own context window), has its own permissions, returns its result when done. Your main agent triggers it, waits for the result, and continues.
Anthropic's canonical definition: "Sub-agents are specialized AI assistants that handle specific types of tasks." They get a custom system prompt, specific tool access, and independent permissions. Claude automatically invokes them when a task matches the sub-agent's description.
The key property: each sub-agent has its own working memory. Your main agent doesn't have to load whatever the sub-agent reads. That's why this pattern scales.
Background Agent
The same idea, but async. Spawned to run in parallel while your main thread keeps going. You don't wait for the result inline. Instead, you check on it later (or it pings you when done).
Background agents are how you do work overnight without sitting at the keyboard. They're also how you parallelize wide research across many independent sessions.
Agent Team
A coordinated group of sub-agents working together with shared structure. One agent typically plays orchestrator, others play specialists or workers. The team produces a single combined output.
Anthropic's definition: "sessions that communicate with each other" for sustained parallelism. Teams have a hierarchy. They have an orchestrator. They have rules about which agent owns which files.
The four levers that shape a sub-agent.
Sub-agents aren't just generic helpers your main agent borrows when needed. You can shape them. Each one is a small configuration with four levers you control:
- Description. Plain-English summary of what the sub-agent is for. Claude reads this when deciding whether to auto-invoke. A description like "reviews Python code for security vulnerabilities" tells Claude to spawn this sub-agent any time security-related code work comes up.
- System prompt. The sub-agent's standing instructions. What conventions to follow, what tone to use, what to refuse to do. This is where your domain knowledge lives.
- Tool access. The exact list of tools this sub-agent can use. A research sub-agent might get web search and Firecrawl but not file editing. A code-reviewer gets read access but no write. A test-runner gets bash, scoped to
npm testonly. - Permissions. The sub-agent's own approval rules, independent of your main agent's. A sub-agent can run more strictly than the main thread (every action requires approval) or more freely (auto-approve specific actions).
Where they live. Sub-agents are Markdown files with YAML frontmatter. User-level ones go in ~/.claude/agents/ and are available in every project. Project-level ones go in <project>/.claude/agents/ and are scoped to that one repo. Same pattern as skills and slash commands.
Easiest way to create one. Run /agents inside Claude Code. It opens a guided flow that lets you describe the sub-agent in plain English, generates the identifier, description, and system prompt for you, and lets you pick the tools it should have access to. The output is a Markdown file in the right folder, ready to use. The agent does the boilerplate for you. You shape the four levers above and let it write the file.
You're already using some. Claude Code ships with built-in sub-agents you may have invoked without realizing it: Explore (read-only Haiku agent for searching and analyzing codebases), Plan (research-only agent used during plan mode), general-purpose (full-tool agent for complex multi-step work). When Claude has been "checking your repo" or "exploring before answering," it's been delegating to one of these the whole time.
The discipline this enables: build a small library of specialized sub-agents for your own workflows. A code-reviewer that knows your conventions. A research agent that uses your preferred sources. A documentation-writer that matches your team's voice. Once you have three or four, you stop reinventing the prompts.
The model-tier hierarchy.
There's a fifth lever underneath the four above, and it's the one that turns sub-agents from nice to have into cheap enough to run by the dozen: each sub-agent can run on a different model. The orchestrator can be the most capable model in your stack. The workers can be the cheapest. The team still produces one synthesized result.
Hunter Canning, who runs the merge-2-main library, has the cleanest articulation of how to map models to roles. Three tiers, top to bottom:
| Tier | Role | What it does |
|---|---|---|
| Opus | Orchestrators | Plan the work, delegate to the tiers below, synthesize the final result. The most expensive context, used only for judgment calls. |
| Sonnet | Mid-tier sub-agents | Specialized work, mid-complexity tasks. Domain specialists that need real reasoning but not the full Opus tax. |
| Haiku | Worker bees | High-volume grunt work, extraction, classification, summarization. Fast and cheap. This is where the bulk of the tokens go. |
"Anytime the main heads of the teams, for me, are running on Opus, and they're the orchestrators. The sub-agents are Sonnet, and then I have sub-agents under the Sonnet ones that I just call worker bees, and they're Haiku. The lowest ones can just do some grunt work, so you're not burning your entire token stuff on fire in one go. That's super important when you start to scale out."
You encode this hierarchy in your sub-agent definitions (the system prompts, the SOPs in markdown). Claude Code will let you pin a model per sub-agent, so the orchestrator's model field reads claude-opus, the workers' reads claude-haiku, and the math works itself out. Real-world cost reduction on heavy research work runs five-to-ten-x compared to running everything on the top tier.
The documented version of this pattern lives in Hunter's open-source library at github.com/ragnos-labs/merge-2-main. The library calls the hierarchical-team shape Hivemind. The Opus/Sonnet/Haiku tier mapping is one expression of it.
Why this saves your context window.
The thing nobody tells you about sub-agents up front: the reason this architecture exists is to protect your context window. Every Claude session has one. It's the agent's working memory, and it has a hard limit. Once it's full, the agent starts forgetting the earliest things you told it. Quality drops. Money keeps spending. You feel it as "Claude got dumber three hours in." That's a full working memory, not a worse model.
One agent doing everything fills its own working memory with every file it reads, every page of docs it scrapes, every tool result it sees. Ten articles in, the memory is bloated. Fifty in, you're losing fidelity. A hundred in, you're at the wall.
Sub-agents fix this because each one has its own working memory. The main agent sends a sub-agent off with instructions. The sub-agent reads whatever it needs (the 100 articles, the 50 files, the long transcript), processes it inside its own memory, and returns a short result. The main agent never sees the raw material. Just the summary.
You're researching a topic and want to read 100 articles to find a consensus.
One-agent way: Your main agent reads all 100. By article 30 it's losing earlier ones. By 60 it's making things up. By 100 it's a mess. Cost: 100 articles of tokens in one agent.
Sub-agent way: You spawn 10 sub-agents, each reads 10 articles, each returns a 1-page summary. Your main agent receives 10 pages and synthesizes. Cost: ~10 pages of tokens in the orchestrator. The 100 articles stay distributed across 10 fresh working memories that get thrown away when each sub-agent finishes.
Now stack the tier hierarchy on top. Those 10 worker sub-agents don't have to be the same model as the orchestrator. They go to Haiku. The orchestrator stays Opus because it needs the judgment to synthesize. The workers go Haiku because they just need to read and summarize. The orchestrator gets 10 short summaries it could have written itself on a good day. The whole job costs a fraction of one Opus agent doing the same work end to end.
Claude Code does have a fallback for when your working memory fills up: a feature called compaction. The system automatically summarizes earlier parts of your conversation to free up space. It's a real safety net, but it's a lossy operation. Every time it runs, you lose detail you might have wanted later. Sub-agents are the proactive version of the same fix. Instead of stuffing your main memory until compaction has to run, you spawn sub-agents to do the heavy reading and only return summaries. You stay below the compaction threshold by design, and your main thread keeps its full memory of what you've decided together.
The discipline this builds is simple: every time you're about to ask your main agent to do something, ask first, "could a sub-agent process this and hand me back a summary?" Most of the time, yes. That's the whole game.
Two-stage self-verification.
There's a specific shape that turns sub-agents from "save my context window" into "check your own work before you scare me". Tyler has retold this one on the AI Build Lab Lightning Lessons several times because it's the moment the architecture becomes safety-relevant.
The story is Joe Fishback, a residential plumber Tyler built a commercial-bidding system for. Joe got a bid on a piece of property. Tyler's agent fleet was reading the geological reports for the parcel as part of its background research. One of the worker agents flagged something alarming: a rock formation on one corner of the lot that would force Joe to bring in heavy excavation equipment to lay pipe at the required depth. That kind of finding would blow Joe's bid math.
Here's the pattern. Instead of just reporting the alarm, the agent spawned a verification team. The verification team's job: take the original finding and check whether it was actually relevant to where Joe was going to dig. The verifiers came back with the answer. The geological hazard was on a corner of the parcel Joe wasn't going near. The original alarm was real but didn't apply. The agent then surfaced both readings to Tyler and Joe: the original concern, and the disconfirmation.
The shift this represents: "agent reads, agent reports" becomes "agent reads, agent self-doubts, agent spawns verifier, agent reports both readings." Two-stage reasoning with a self-spawned verification team in the middle. The human gets the conclusion and the dissenting evidence.
This is the same primitive whether the alarm is a geological hazard, a contract clause that looks like an IP grab, a numerical result that doesn't pass a sanity check, or a piece of source material that contradicts the rest of the corpus. The pattern is: spawn a fresh agent whose only job is to disconfirm or confirm a specific claim made by another agent, then surface both sides to you.
Why it works. The verifying sub-agent has a fresh working memory and a narrow brief. It can't anchor on the original finding because it didn't read the original material. It reads only what's needed to check the specific claim. That's structurally hard to do inside a single agent's session, because by the time the agent has read the alarming thing, it's primed by it. Splitting the read and the verify across two agents removes the prime.
On the same Joe Fishback build, Tyler's fleet ran 19 research agents in parallel for the first bid (blueprints, supplier pricing, public records, licensing, competitor research). Three separate harnesses (Claude Code, Codex CLI, Gemini CLI) extracted the bid blueprint independently and triangulated to one Finalized Source of Truth. The final automated bid validated within roughly 2% of Joe's experienced hand bid on a follow-on commercial job. Two-stage self-verification is one slice of how a fleet that size stays trustworthy.
The anti-pattern this teaches against.
The biggest mistake new builders make is never spawning anything. They run Claude as a single agent for every task. Every action waits on every other action. Every approval prompt blocks the next one. They never see the parallelism.
One agent, every approval, all day.
The common early pattern: you approve every edit, treating Claude as a singular agent for the whole session. Every action waits on every other action. No sub-agents ever spawn. By hour two, approval fatigue sets in. This is exactly what auto-mode and sub-agents together are designed to defeat.
The fix is one prompt away. Tell your agent: "Send three research agents to look into X, Y, and Z in parallel. Come back when all three have results." That single prompt spawns three sub-agents. They run at the same time. You get back what would have taken three serial runs.
The five named patterns.
Those three primitives are your LEGO bricks. The named patterns below are the assembled LEGO sets. They come from merge-2-main, Hunter Canning's open-source library of multi-agent orchestration patterns. The repo is public, tool-agnostic, and battle-tested in production from 2-agent setups up through 30+ agent fleets.
"Agents amplify plans. A good plan with 10 agents produces 10x the output. A bad plan with 10 agents produces 10x the mess." Worth committing to memory before you start spawning teams.
Worker Swarm
A group of sub-agents doing the same kind of work in parallel. Example: ten agents each summarizing a different chapter of a long document. Each does the same job, just on different input. No coordination needed because they don't overlap.
Research Swarm
A group of sub-agents researching different angles of the same question in parallel. One agent searches developer docs. One searches blog posts. One searches your local corpus. They return findings, an orchestrator synthesizes.
The shape of this pattern: tell your agent to send out ten Haiku research agents in parallel, each doing a focused web search via Firecrawl. They come back, the orchestrator finds the consensus. Same query, multiple angles, one synthesized answer.
Hive Mind 2-Tier
Orchestrator plus workers. One agent plans and delegates. Workers execute. The orchestrator synthesizes results at the end. This is where the token economics kick in: the orchestrator never loads the raw material the workers process, so the planning agent stays in cheap context while workers do the heavy reading.
Map this to the tier hierarchy: Opus orchestrator + Haiku workers. That's the lowest-cost shape that still produces orchestrator-grade synthesis.
Hive Mind 3-Tier
Orchestrator plus specialists plus workers. The middle tier provides structure that pure flat workers can't. Specialists are domain-specific (a security specialist, a documentation specialist, a testing specialist). Each specialist commands its own pool of workers.
Map this to the tier hierarchy: Opus orchestrator + Sonnet specialists + Haiku workers. The full three-stack. Hunter reaches for 3-Tier when the work itself is plural-discipline.
Patchwork
Different agents own different files, with no overlap. There's no orchestrator synthesizing at the end. Each agent's output is final for the files it owns. The "patchwork" is the union of everything they produced, with hard boundaries between zones.
The load-bearing rule: non-overlapping file ownership. Agent A writes to src/auth/*. Agent B writes to src/billing/*. They can read each other's output, but never write into each other's zone. Merge conflicts become structurally impossible.
The full library, including the file-ownership rules, the runtime adapters for Claude Code / Codex / Gemini CLI, and worked examples, lives at github.com/ragnos-labs/merge-2-main. Hunter's posture on it: opinionated about process, reviewability, and scope control. Not "spawn 20 agents and pray."
The demo moment.
The starter prompt at the top of this page runs a Research Swarm against any topic you name. What happens behind the scenes:
- Your main agent reads the prompt. It doesn't do any research itself.
- It spawns three sub-agents. Each gets a focused task and its own working memory. They run in parallel.
- After roughly the time it would have taken one agent to do one of those searches, all three return their findings.
- The main agent synthesizes. You get one consensus document with sources from three independent angles.
The visible-to-you change: multiple agents running with a single prompt. This is the moment "agent-native" stops being a phrase and starts being a way of working.
How to pick the right pattern.
Worker Swarm vs. Research Swarm vs. Hive Mind vs. Patchwork isn't about complexity. It's about shape of work.
| Your task looks like... | Reach for... |
|---|---|
| Same job, many inputs (summarize 20 chapters, refactor 50 files) | Worker Swarm |
| Same question, many angles (research topic X from three lenses) | Research Swarm |
| Plan + execute + synthesize, single domain (refactor + test + document this feature) | Hive Mind 2-Tier |
| Plan + multiple specialties + many workers (build a new product) | Hive Mind 3-Tier |
| Different agents own different files, no synthesis needed | Patchwork |
| An agent's finding looks alarming and you want a second opinion | Two-stage self-verification |
The starting move for most builds is the Research Swarm. Easiest to demonstrate, easiest to reason about, produces the most obvious "wow this is actually faster" moment the first time you spawn one.
What changes for you.
The architecture is half of it. The shift in how you think is the other half. Three changes you'll feel:
- You stop asking one agent to do everything. You start designing a small team. Your prompt becomes "spawn three agents to do these three things in parallel" instead of "do these three things one after another."
- You start protecting your main agent's working memory. The orchestrator (your main thread) is your most expensive context. You learn to push the heavy reading down to workers so the orchestrator stays lean, and you let cheap Haiku workers do the bulk of the tokens.
- You begin to think in plans, not commands. Hunter's "10x output vs. 10x mess" rule lands the first time you hand a bad plan to ten agents. The discipline is in the plan, not the spawning.
The shift names itself the first time you see six agents run from one prompt and come back with a synthesized result you didn't have to manage.
Where this leads.
The patterns above are workshop-scale. They live on your computer, in your single Claude Code session, returning results in seconds or minutes. When you take this further, the team you build out of these becomes capable of real production work.
The closest example in the AI Build Lab world is the Joe Fishback Plumbing build that Tyler created. Joe is a residential plumber who wanted to improve his commercial bidding process, where the dollar amounts and the complexity of estimating jump by an order of magnitude. The build used 19 research agents in parallel across blueprints, supplier pricing, public records, licensing, and competitor research. Three independent extraction harnesses (Claude Code + Codex CLI + Gemini CLI) ran the same blueprint analysis separately, then triangulated to a single Finalized Source of Truth. The geological-corner self-verification you read about above was one of dozens of two-stage checks that ran inside this build. The final automated bid validated within roughly 2% of Joe's experienced hand bid on a follow-on job.
That's the same architecture you're learning here, just scaled up. Research Swarms, Hive Mind orchestration, file-ownership rules, two-stage verification. The patterns don't change. The size of the team does.
If you want to go this direction, the path through Stage 05 (autonomous operations) and into Summer Camp is built around it.
Where to go next.
You have the architecture. Three natural next moves: