The biggest recent AI upgrade isn’t a smarter model. It’s giving the same model teammates.
We’re seeing diminishing returns with frontier models. New releases that used to feel like step changes now feel more incremental. But going from a single Claude Code to an entire team of Claude Code agents? That’s a different kind of upgrade.
With Opus 4.6, Anthropic also shipped Agent Teams in Claude Code. Here’s my complete breakdown so that you can understand how this new feature works and how to start using it.
The Sequential Problem
I recently shared my ‘Ship Daily’ system where Claude Code resolves Linear issues end-to-end while I do other work. For the unfamiliar, think of Linear as a fancy to-do list for app/product builders. Issues are the to-dos and projects group related to-dos.
The system works incredibly well. But it’s sequential. I have to wait for one issue to finish before kicking off the next. A small project with 5 issues takes around 2.5 hours.
Agent Teams promise two things:
- Parallelization — multiple teammates split the workload, each taking on an individual issue and working simultaneously
- Collaboration — teammates communicate with each other, sharing context useful for each other’s tasks. A practical way to think about it: we know more thinking produces better output. A team of agents gives you a lot more thinking tokens than a single agent.
My ultimate goal is a lead Claude Code managing a team of Claude Codes: each resolving a Linear issue while the lead oversees the project. Entire projects completed autonomously in a fraction of the time.
That’s the dream at least. Let’s break down how it actually works.
How Agent Teams Work
A team is always made up of 1 lead + 1 or more teammates.
The Lead & Orchestration
The team lead spawns and shuts down teammates, assigns tasks from a shared task list, and orchestrates the whole process. Teammates communicate to the lead when their task is complete.
If a teammate finishes its initial task, the lead might assign it a new one rather than spawning a fresh teammate. This can actually be pretty useful for dependent tasks.
Say you have task 1 and task 2, where task 2 is blocked by task 1. When agent X completes task 1, it already has all the context from those changes which is likely relevant to task 2. So it makes more sense to just assign task 2 to agent X rather than spawning a new teammate with less context.
Communication
Teams have a shared “Mailbox” (the messaging system). Teammates can either DM a specific teammate or broadcast to everyone.
Important cost note: broadcast messages are read by all teammates. For a team of 10, one broadcast becomes input tokens for all 10 Claude Code instances. That adds up fast.
It’s actually kind of fun seeing them work together. Here, the lead sends a gentle “nudge” telling a teammate to save output to a file. The teammate responds that it’s already saved it.
When the lead gets confirmation that a task is complete, it sends a shutdown request.
The teammate responds with a message approving the shutdown. So polite!
Users can also pop in to chat with any teammate at any time, providing some human-in-the-loop steering. Though I don’t see this as super practical — each teammate works through tasks quickly and monitoring 5 AI agent conversations in real time is... a lot.
Team Size
To my (and Claude's) knowledge, there's no limit to team size, but Anthropic recommends keeping teams small.
Makes sense. Dozens of agents trying to coordinate simultaneously would probably lead to unfocused conversations and more distraction than help.
Getting Started
Agent Teams is disabled by default.
Agent Teams is disabled by default. To enable, add this to your project's .claude/settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Then just tell Claude when you want a team. For example:
Create an agent team to audit our app's performance. Spawn four reviewers:
- One analyzing database query efficiency and N+1 problems
- One checking frontend bundle size and render performance
- One reviewing API response times and caching strategies
- One examining memory usage and potential leaks
Have them each investigate and share findings with each other.
In general, Agent Teams make sense when a task benefits from both parallel work and agents communicating — research and review, building new modules, debugging competing hypotheses, cross-layer changes spanning frontend/backend/tests.
Agent Teams vs Subagents
In terms of function, the key difference comes down to communication.
Table from Claude Code docs highlighting the differences between subagents and agent teams
Subagents can't be communicated with. They're given an input, run independently, and return an output. I've always thought of them more as tools than agents. Agent teammates, on the other hand, can send messages to each other and receive messages from the user. From the docs:
Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.
The rule of thumb: if your workflow can be kicked off with a single input, a subagent works fine. If the task benefits from agents sharing findings, challenging each other, or adapting based on what others discover, use an agent team.
The Subagent Limitation
Here’s something I couldn’t find in the official docs: agent teammates can’t call subagents. Found this out through testing.
This is pretty significant in my book.
I have a lot of workflows that use subagents for specialized tasks, and more importantly, to preserve the context window for the main Claude Code. My guess is the Agent Teams implementation is similar to subagents under the hood — sharing the same guardrail against recursion.
Here’s what happened: I have a skill that requires a subagent called “investigator.” When an agent teammate invoked the skill, it mentioned not having a teammate called “investigator” and just... tried to do the task itself. No error, no message to the team lead. It just proceeded without the critical context from the investigator’s prompt. The teammate doesn’t even have the Task tool anymore (which is what Claude normally uses to call subagents).
The practical impact: if you have slash commands or skills that leverage subagents, you can't use them plug-and-play with Agent Teams. Porting existing workflows takes more thought and effort than you might expect.
Cost 💸
The cost increase is staggering. From Anthropic:
Agent teams use approximately 7x more tokens than standard sessions... Keep team tasks small and self-contained to limit per-teammate token usage. See agent teams for details.
Using myself as an example, I'm normally fine on the 5x ($100) max plan and rarely hit a session limit. After enabling Agent Teams for testing, I hit my limit pretty quickly with more than an hour to go before my session limit reset.
My setup: 1 lead and 3 teammates, tasked with resolving a Linear project with 7 issues. The lead assigned one issue per teammate at a time, remaining issues waited in the queue for a teammate to free up. (You can read more about the full use case [here].)
To get the most out of Agent Teams, you’ll probably need to invest in tuning the team lead’s orchestration. Both for performance and for cost efficiency. This point from the docs is worth highlighting:
Clean up teams when work is done. Active teammates continue consuming tokens even if idle.
So Agent Teams can be expensive, and from a cost perspective, their use may not always be justified.
But that doesn’t mean they can’t generate high ROI for specific applications.
The same was true when subagents were first introduced as they added significant cost. But their value quickly justified it in workflows where depleting the main Claude Code’s context window cost a lot more.
Looking Ahead
The potential is pretty clear. Multiply a single Claude Code agent by 2x, 5x, etc., leads to faster output through parallelization and higher quality through more thinking tokens. For now at least, it comes with a much higher cost and some real limitations (especially the subagent restriction).
But costs come down and limitations get addressed. I’ll continue to test Agent Teams with more complex workflows and share what works. Especially with upgrading my Ship Daily system to resolve entire Linear projects end-to-end.
If you’ve been experimenting with Agent Teams, reply and let me know. I’m curious what use cases are (or aren’t) working for you.