Claude Code Subagents: Build a Small Team in One Repo
One agent writes, a second one checks, and you keep the right to say no. That is the whole team.
Claude Code subagents are the cheapest way to stop one long session from doing everything at once. You give a task its own worker, with its own context and its own tools, and you get a short report back instead of a flooded conversation.
Most guides show you twelve subagents, or a hundred. I run my content pipeline on a much smaller idea. One agent writes. A second agent checks. I keep the veto.
Here is what subagents are, how to build one, when they help, and the quiet way a reviewer fails.
Key takeaways
- A subagent runs in its own context window with its own system prompt, tools and permissions, and hands back only a summary.
- Use one for work that floods your context, like research across many files, or for a review that should not share the writer's reasoning.
- A reviewer that approves everything is not a team. Test what it rejects before you trust what it passes.
What are Claude Code subagents?
The official docs describe subagents as specialized assistants for specific kinds of tasks. Each one runs in its own context window with a custom system prompt, its own tool access and independent permissions. When a task matches a subagent's description, Claude delegates the work, and the subagent returns only a summary.
That last part is the point. The docs say performance degrades as the context window fills. A research subagent can read thirty files. Your main conversation gets ten lines back.
Two things subagents are not:
- Not a separate account or budget. They work inside your session, and their requests count toward the same usage limits as the main conversation.
- Not a copy of your chat. A fresh subagent does not see your conversation history or the files Claude already read. It only knows what the delegation message tells it. Write that message like a brief for a contractor.
Claude Code also ships built-in subagents. Explore is a fast, read-only agent for searching a codebase. Plan does read-only research while you are in plan mode. General-purpose handles multi-step tasks that need both reading and acting.
How to create Claude Code agents of your own
A custom subagent is a Markdown file with YAML frontmatter. The body becomes its system prompt. Project agents live in .claude/agents/, personal ones for all your projects in ~/.claude/agents/. If both define the same name, the project version wins.
Only name and description are required. A reviewer can be this small:
---
name: fact-checker
description: Checks a finished draft against the project's source files. Use after every draft, before anything is published.
tools: Read, Grep, Glob
model: sonnet
---
You review drafts. You did not write them and you do not rewrite them.
For every number or claim, find the line in the source files that supports it.
Report each claim, its source line or MISSING, and a verdict.
Reject the draft if a single claim is MISSING.
Three fields do most of the work:
- description decides when Claude delegates. The docs note that phrases like "use proactively" encourage automatic delegation.
- tools is an allowlist. Leave it out and the subagent inherits every tool. A reviewer that can only read cannot quietly "fix" the draft into something you never asked for.
- model routes the job:
sonnet,opus,haiku,fable, a full model ID, orinherit. Simple checks can run on a cheaper model.
You can invoke a subagent three ways. Claude picks it automatically from the description. You ask by name ("use the fact-checker subagent on the new draft"). Or you @-mention it, which guarantees that exact subagent runs.
When subagents help
Research that would flood your context. The docs suggest prompts like "use subagents to investigate X". The subagent burns its own tokens and returns the finding.
Parallel work that shares no state. By default up to 20 subagents can run at once. Three independent questions, three workers, one summary each.
A reviewer that never saw the reasoning. This is the one I care about. A reviewer in a fresh subagent context, in the docs' words, "sees only the diff and the criteria you give it". A writer grading its own work tends to agree with itself.
When subagents are the wrong tool
- Small tasks. If you can describe the change in one sentence, delegation costs more than it saves.
- Tasks that live in the conversation. A fresh subagent starts empty. If the value is in the last hour of back and forth, keep the work in the main session.
- Knowledge you want everywhere. A style guide is not a worker. That is a skill: content that loads into your current context when needed. The difference is in what Claude skills are.
- Rules that must hold every time. A subagent is still a model making decisions. "Never touch the .env file" belongs in a hook. More on that in my Claude Code best practices.
- Several long sessions coordinating with each other. That is what agent teams do, and the docs list them as experimental and disabled by default. Subagents work inside one session.
My Claude Code agents team: one writes, one checks, I keep the veto
Since 2026-10-19, an agent writes my X posts 10 to 14 days ahead. It runs as Claude Code, headless on a cron schedule on my own Hetzner server. A second agent checks the posts. I approve nothing in advance. I only stop what I don't like, via Telegram.
Strictly speaking, these are two separate headless runs, not subagents inside one chat. The principle is the same one the Claude Code docs describe as the writer and reviewer pattern: the agent doing the work is not the one grading it.
The human veto is the third role. Approval would make me the bottleneck on every post. A veto does not. If you want the bigger picture of how these pieces connect, I wrote about it in the AI operating system.
The reviewer failure nobody warns you about
The docs warn about one failure: a reviewer asked to find gaps will usually report some, even when the work is sound. Chase every finding and you over-engineer.
My first batch showed the opposite. The reviewer looked at 24 posts on 2026-10-19 and rejected none. Zero out of 24 can mean 24 good posts. It can also mean a reviewer with no teeth. You cannot tell from the approval alone.
So the useful test is simple. Give the reviewer a draft you know is broken. If it passes, the reviewer is decoration.
How to build your first two-agent team
- Write the rules once, where both agents read them. Put them in your CLAUDE.md or a source file in the repo, not in two prompts that drift apart.
- Create the reviewer with read-only tools and a reject rule. It needs a clear condition for "no", not just a request to "check quality".
- Plant a broken draft. A placeholder, an unsupported number. The reviewer must reject it before it touches real work.
- Keep a stop button for yourself. Telegram, a pause file, anything you can hit from your phone.
If you want to go further and build the agent itself from scratch, start with how to build an AI agent.
FAQ
Where are Claude Code subagents stored?
Project subagents live in .claude/agents/ inside the repo, so they travel with the code. Personal ones live in ~/.claude/agents/ and apply to all your projects. Each is a Markdown file with YAML frontmatter, and the body becomes the system prompt.
Do Claude Code subagents share my conversation context? No. A regular subagent starts with a fresh context and does not see your chat history or the files Claude already read. It works from the delegation message Claude sends it, then returns a summary. That isolation is why they keep your main session clean.
Can a subagent start another subagent? Yes. According to the docs, subagents can nest up to three layers below the main conversation by default. To stop a specific subagent from spawning others, leave the Agent tool out of its tools list.
What is the difference between subagents and agent teams? Subagents are workers inside one session that report back to it. Agent teams coordinate several sessions with shared tasks, messaging and a team lead, and are still experimental.
About the author
Tristan Eilenburg. One person. AI systems. Global reach. I write about building systems that work, with evidence instead of hype.
- X: @MrB2Beast
- LinkedIn: Tristan Eilenburg
- Instagram: @mrb2beast
The newsletter goes out once a week. If this one taught you something, the newsletter is where the next one lands first.
Sources
- Anthropic (2026). Subagents. Claude Code Docs. https://code.claude.com/docs/en/sub-agents
- Anthropic (2026). Best practices for Claude Code. Claude Code Docs. https://code.claude.com/docs/en/best-practices
- Anthropic (2026). Extend Claude Code. Claude Code Docs. https://code.claude.com/docs/en/features-overview
