Subagents and agent teams in Claude Code: what they are and when to use each
Short answer: a subagent is an assistant that Claude Code calls to handle part of the work in a separate context and return only the result. An agent team brings together several full Claude Code sessions that work at the same time and message each other. Below, how each one works, what it costs and when it’s worth using.
If you use Claude Code for more than programming, for research, writing, campaign analysis or brand review, you soon run into two terms in Anthropic’s documentation: subagents and agent teams. Both split work across several AI instances, so they look like the same thing. They solve different problems and cost different amounts.
At Headcore we use subagents every day. Our brand operation runs on 17 of them today, organized into six plugins, from brand diagnosis to media analysis. This guide explains both features based on the official Claude Code documentation, checked in October 2026, and on what we learned while building those agents.
If the idea of an agent is still new to you, start with our piece on agentic AI and AI agents.
What a subagent is
A subagent is a specialized assistant that Claude Code calls to handle part of the work. It has its own instructions, its own list of tools it may use and a context window separate from the main conversation. That last point is the reason it exists.
The context window is everything the model takes into account at once: the conversation, the files it has read, the search results. It has a limit, and the fuller it gets, the more the model gets distracted by things that no longer matter. As we showed in how to use AI in branding, much of the quality of an answer depends on what sits in that window.
An example: you ask Claude Code to go through 40 campaign reports. If the main conversation reads all 40, it ends up packed with numbers it will never use again. With a subagent, the reading happens in another context, and the main conversation gets only the conclusion, in a few lines.
What a subagent receives and what it returns
Two details explain most of the stumbles people make at the start. The subagent does not see your conversation. It receives the request Claude writes when calling it, the instructions in its own file and the project context. If a decision was made ten messages ago, it has to be written into the request, or the subagent will work without it.
On the way back, only the final result returns. The searches, reads and attempts stay in the subagent’s context. That saves room in the main conversation, which now relies on the summary. When the summary is wrong, the path that led to the error doesn’t show up in the conversation, and only someone who opens the subagent’s transcript can see where it went off track.
Subagents that the main conversation creates usually run in the background. You keep working while they read and search, and the result arrives as a notification when they finish. Independent research can run in parallel, each piece in its own subagent.
How to create a subagent
A subagent is a Markdown text file with a configuration header and the instructions right below it. Claude Code looks for these files in the project’s .claude/agents/ folder, for agents that only make sense there, and in ~/.claude/agents/, for the ones you want in every project. Plugins can ship their own as well.
Only two fields are required, name and description. Here is an example for someone who handles content:
---
name: voice-reviewer
description: Reviews blog posts, captions and emails against the brand voice guide. Use before publishing any text.
tools: Read, Grep, Glob
model: sonnet
---
You review brand texts. Read the voice guide in docs/voice.md before you start.
Point out each passage that strays from the guide, say which rule it breaks and
suggest a new version of that passage. Don't rewrite the whole text and don't edit files.The field that matters most is description. Claude reads that sentence to decide whether to delegate and to whom. A vague description, such as “helps with texts”, gets the agent called at the wrong moment, or never. One that works says what the agent does and when it should step in.
The tools field limits what the agent can use. In the example, the reviewer can only read and search, so it can’t edit a file by mistake. The model field picks the model, and simple tasks can go to a cheaper one. One caution: Claude Code silently ignores a field with a misspelled name, so check the spelling letter by letter.
To use it, just ask in plain language (“use the voice-reviewer on this post”) or mention the agent with @. Claude also calls the subagent on its own when a task matches the description. If you’d rather not write the file, you can ask Claude Code to create it for you.
Claude Code comes with a few subagents built in. Explore only reads, and it’s meant for searching across many files without spending the main context. Plan is used in plan mode, to gather information before proposing a plan. There’s also a general-purpose one for tasks that require reading and acting.
What agent teams are
Agent teams take the idea further. Instead of a helper that does a task and hands back the result, you get several full Claude Code sessions working at the same time. One of them is the lead, which splits the work, hands out tasks and pulls together what comes back. The others are teammates.
What changes is how they communicate. Subagents only talk to whoever called them. In a team, teammates message each other directly and work from a shared task list, where each one picks up the next free task when it finishes its own. You can also talk to any teammate without going through the lead.
The feature is still experimental and off by default. To turn it on, set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS variable to 1, in your terminal environment or in settings.json. Then describe the task and ask for the team in plain language. Teammates show up in a panel below the input box, and you can open each one.
A request that works well, adapted from an example in the documentation to a marketing case: “Create a team of three teammates to review this landing page. One looks at how clear the offer is, another looks at SEO and the third plays a skeptical customer. Have them discuss with each other before giving me the conclusion.”
Subagents or agent teams: the difference
| Subagents | Agent teams | |
|---|---|---|
| Context | Their own; the result goes back to the caller | Their own, fully independent |
| Communication | Return the result to the caller | Teammates message each other directly |
| Coordination | The main conversation manages everything | Shared task list and messages |
| Best for | Focused tasks where only the result matters | Work that needs discussion between the parts |
| Token cost | Lower, because only the summary comes back | Higher, because each teammate is a separate instance |
| Status in Oct 2026 | Stable feature | Experimental, off by default |
Source: Claude Code documentation, October 2026.
A quick way to decide: if the agents don’t need to talk to each other, use subagents. If they need to discuss, challenge each other’s findings or split a large job with dependencies between the parts, a team starts to be worth the cost.
When it’s worth it, and when it isn’t
Both features use more tokens than a single conversation. Each subagent spends tokens while it works, and that usage counts toward the same limit as the main conversation. In a team, the cost grows with the number of teammates. To fix a text, adjust a page or answer a question, one agent alone is faster and cheaper.
Subagents pay off when a task produces a lot of intermediate material and little result, like reading dozens of files, sweeping a folder or checking a list of URLs. They also pay off when you want the same task done the same way every time, with the same rules and the same tools.
For teams, the documentation recommends starting with three to five teammates and notes that three focused ones usually get more done than five scattered ones. It also suggests starting with research and review, which don’t require editing files. Two teammates editing the same file overwrite each other’s work.
The known limitations call for someone keeping an eye on things. Each session holds a single team, and teammates can’t form teams of their own. When you resume a session, teammates don’t come back with it. Task status sometimes lags, and the lead may call the work finished too early.
How we use subagents at Headcore
Our brand operation runs on Growth System™, the set of six Claude Code plugins we built, with 17 subagents in total. Each plugin covers one stage: building the brand’s Brand Brain, writing and composing pieces, designing pages, producing video, analyzing media and judging the work before delivery. The Brand Brain holds positioning, voice, visual rules and decisions, and the agents read from it before producing anything.
Three design choices helped more than we expected. The first was giving each agent a single question. The copywriter writes and doesn’t decide format or visuals. The art director defines the treatment of the piece and doesn’t execute it. With one job per agent, the description stays clear and Claude gets the delegation right.
The second was putting the separate context to work for analysis. In the media plugin, the analyst and the operations check run in parallel. The analyst says what changed in the numbers and why; the check confirms whether the operation did what the strategy planned. Because neither reads the other’s report, neither pulls the other toward its own conclusion.
The third was limiting tools. Agents that only analyze have read access, with no permission to edit files, which rules out a whole class of accidents. The reviewer in the example above follows the same logic and checks texts against rules like the ones in our map of AI writing patterns.
We also get things wrong. Sometimes an agent answers from memory when it should have checked the source. That’s why no piece goes out without human review, and every new rule goes into the Brand Brain, so the same mistake doesn’t come back with the next brand. We haven’t yet measured how much time this setup saves, and that number is still open.
Where to start
Start with one subagent for a task you repeat every week and that involves a lot of reading: reviewing texts against the voice guide, checking a page’s links, summarizing reports. Write the description with the moment it should be called in mind, give it only the tools it needs and test it on a real case before you trust it.
Once two or three subagents are working, try a team on a review job, with three teammates looking at the same piece from different angles. Follow what each one does and stop when your own review becomes the bottleneck. If everything the team delivers has to be redone, revise the instructions before thinking about more agents.
The full series
This piece is part of a five-part series on AI agents applied to brand work:
- Subagents and agent teams in Claude Code (this piece)
- Skills and plugins in Claude Code
- CLAUDE.md and Brand Brain: brand memory for AI
- How to review AI-generated content
- How we use AI in Headcore’s operations
Frequently asked questions
What is the difference between a subagent and an agent team in Claude Code?
A subagent does a task in its own context and returns only the result to whoever called it. In an agent team, several full Claude Code sessions work at the same time, message each other directly and share a task list, under a lead session. Subagents cost less; teams are for work that needs discussion.
Can I use subagents without knowing how to code?
Yes. A subagent is a text file with a short header and instructions in plain language. You can also ask Claude Code to create the file from a description of what you want. Using it is plain language too: just ask Claude to use the agent by name.
Do subagents use more tokens?
Yes. Each subagent spends tokens while it works, and that usage counts toward the same limit as the main conversation. In return, the main conversation receives only the summary and stays lighter. Agent teams use far more, because each teammate is a separate Claude instance.
Can a subagent call another subagent?
Yes. By default, a subagent can create others up to three levels below the main conversation, and that limit can be changed. Agent teams work differently: only the lead session creates teammates, and teammates can’t form teams of their own.
How many subagents can run at the same time?
The default limit is 20 concurrent subagents, adjustable through an environment variable. In practice, a few well-described agents get more done than many generic ones.
Are agent teams ready for everyday use?
As of October 2026, the feature is still experimental and off by default. It works well for research and review, but it has known limitations: one team per session, teammates that don’t return when a session is resumed and task status that sometimes lags. For daily use, subagents are the safer route.
Sources: Claude Code documentation on subagents and on agent teams, checked on 21/10/2026.
