If you’ve been using Claude Code for a while, you already know subagents. They’re the workhorses behind the Task tool — you send one off to research something, it comes back with results, and you move on. Simple, effective, and cheap on tokens.

But Anthropic recently shipped something more ambitious: agent teams (sometimes called swarms). And the natural question is — when do you actually need a team instead of a subagent?

I’ve been thinking about this since the feature landed, and the answer isn’t “always use the shiny new thing.” It’s more nuanced than that.

A quick primer on agent teams

Agent teams let you spin up multiple Claude Code instances that work in parallel, each with their own context window. There’s a lead agent that coordinates, and teammates that do the actual work. They communicate through a shared task list and a messaging system — think of it as a lightweight project board with a chat channel.

You enable them with a flag in your settings:

1
2
3
4
5

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Then you describe what you need in plain language. Something like: “Set up a team — one person on the API layer, one on the frontend, one writing tests.” Claude takes care of the rest.

Worth noting: this is still experimental. It works, but it has rough edges. More on that later.

The real difference between subagents and teams

On the surface, both subagents and teams delegate work to separate context windows. But the way they operate is fundamentally different.

A subagent is a function call. You send it a task, it does the work, it returns a result. The main agent stays in control. Communication is one-directional — subagent reports back, main agent decides what happens next. If you need three subagents to work on related things, the main agent has to juggle all three results and figure out how they fit together.

A team is a group of peers. Each teammate runs independently. They can message each other directly. They coordinate through shared tasks with dependency tracking — when one teammate finishes something, it automatically unblocks the next. The lead agent sets direction but doesn’t micromanage every step.

The mental model that works for me: subagents are like calling a function. Teams are like staffing a project.

When subagents are the right call

Subagents win when the work is contained and independent. A few scenarios where I’d reach for a subagent without hesitation:

• Searching a codebase for how a specific pattern is used across files
• Reading and summarizing a config, a doc, or an unfamiliar module
• Running a one-off check — “does this dependency exist anywhere?” or “what’s the current state of this migration?”
• Generating a single artifact — a test file, a config, a data transformation

The key characteristic: the result flows back to you, and you decide what to do with it. There’s no need for the subagent to talk to anyone else. The token cost stays low, and you keep tight control over the process.

If your problem can be broken into independent queries that don’t need to know about each other’s results — subagents are faster, cheaper, and simpler.

When agent teams start making sense

Teams earn their cost when the work requires coordination between moving parts. Here’s where the switch happens for me:

When you need multiple perspectives on the same problem. Say you’re debugging something tricky and you have three competing hypotheses. With subagents, you’d send each one off, get three reports back, and synthesize them yourself. With a team, the investigators can actively challenge each other’s findings, share counter-evidence, and converge on the real cause without you playing traffic cop.

When parallel work has dependencies. Frontend and backend changes for the same feature. A refactor that touches the data layer, the API, and the tests. If these pieces need to stay aware of each other’s progress — maybe one teammate’s API contract affects another’s frontend implementation — a team handles that naturally through its messaging and task system.

When the scope is too large for a single context window to reason about effectively. This is the technical argument that convinced me. LLMs degrade as context grows. Dumping an entire codebase exploration, a design discussion, and an implementation plan into one context window means the model loses focus. Splitting that across specialized teammates, each with a clean, narrow context, produces better reasoning at every step.

When review needs multiple lenses. Security, performance, test coverage, and code style are genuinely different concerns. A single pass tries to hold all of them in mind simultaneously. Separate reviewers with dedicated focus tend to catch more.

A practical decision framework

Here’s the rough heuristic I’ve landed on:

The honest truth: most day-to-day tasks are still subagent territory. Teams are for the cases where you’d normally need to orchestrate multiple rounds of back-and-forth manually.

Things to watch out for

Since this is experimental, a few practical notes:

• Token costs add up. Each teammate is a full Claude Code instance. Three teammates means roughly 3x the token burn. Make sure the coordination value justifies it.
• The lead agent sometimes wants to do the work itself instead of delegating. There’s a delegate mode (Shift+Tab) that restricts it to coordination only — use it when you want clean separation.
• Task status tracking isn’t perfect yet. Teammates occasionally forget to mark tasks complete. It’s not a dealbreaker, but don’t assume the task board is always accurate.
• One team per session. You can’t nest teams or have teams spawn sub-teams. Keep your structure flat.
• Start small. Research tasks, code reviews, and well-scoped feature work with clear file ownership are good first candidates. Save the ambitious multi-service refactors for when you’ve built intuition about how the coordination works.

The skill that actually matters

Whether you’re using subagents or teams, the bottleneck is the same: how well you decompose the problem.

A vague prompt to a team of five agents produces five mediocre outputs. A well-structured set of tasks with clear boundaries and specific deliverables produces focused, useful work — whether that’s one subagent or a coordinated team.

The tooling is getting better fast. The ability to break a problem into the right-sized pieces and decide which tool fits each piece — that’s on us.

Sources / references

https://addyosmani.com/blog/claude-code-agent-teams/

Planned case study

I plan to do a hands-on example of using agent teams and will share the GitHub repository once it’s ready.