I've spent months building Claude Code plugins around subagents. My ai-workflow plugin breaks features into token-aware phases and runs each one in a parallel subagent context. It works well. Subagents complete their phases, report results, and the orchestrator moves on.
Then Anthropic shipped Agent Teams in Claude Code 2.1.32, and I realized what I'd been working around: subagents can't talk to each other. Every piece of coordination has to flow through the main agent. For independent phases, that's fine. For work where parallel tracks need to share discoveries, challenge assumptions, or agree on interfaces, it's a bottleneck.
Agent Teams remove that bottleneck. Teammates are full Claude Code sessions with their own context windows, a shared task list, and direct peer-to-peer messaging. The lead coordinates work, but teammates can message each other, claim tasks independently, and self-organize. It's a different model of parallel work. I tested it on an OAuth implementation the day it shipped (February 2026) and the difference was immediate. I don't think I'll go back to forcing subagents into coordination roles they weren't designed for.
What Subagents Do Well (And Where They Stop)
Subagents are isolated workers. You give them a task, they execute in their own context window, and they return a summary to the main agent. This is genuinely useful for a lot of work:
- Research: Read 30 files across the codebase, return a paragraph of findings
- Phase execution: Implement a self-contained feature phase with clear boundaries
- Context isolation: Do expensive work without bloating the main conversation
- Verification: Run security audits or code reviews in parallel
My ai-workflow plugin relies heavily on subagents, and that won't change. Each implementation phase is designed to be independent, targeting 30-50k tokens, with clear acceptance criteria. Subagents handle this perfectly because there's nothing to coordinate between phases. Phase 2 depends on Phase 1 being complete, not on an ongoing conversation between them.
The limitation shows up when workers need to coordinate in real time. Subagent A finishes an API endpoint, but Subagent B building the frontend component doesn't know what response shape A decided on. The main agent becomes a relay, passing context between workers that can't see each other. For simple handoffs, this is manageable. For ongoing collaboration, it creates friction that slows everything down.
Agent Teams: Teammates, Not Workers
Agent Teams are architecturally different from subagents. Instead of lightweight workers reporting to a parent, you get full Claude Code sessions that communicate directly through a shared mailbox and task list.
The Architecture
An Agent Team consists of four components:
- Team Lead: Your main Claude Code session. Creates the team, spawns teammates, coordinates high-level direction.
- Teammates: Independent Claude Code instances. Each has its own context window, reads your CLAUDE.md and project context, and works autonomously.
- Shared Task List: A centralized list of work items with dependency tracking. Teammates claim tasks, mark them complete, and blocked tasks unblock automatically.
- Mailbox: Direct messaging between any agents. Teammates can message each other without going through the lead.
The lead doesn't need to micromanage. Teammates claim available tasks from the shared list, do their work, and communicate directly when they need to. The lead steps in for high-level decisions, synthesizing findings, or redirecting approach when something isn't working.
Getting Started
Agent Teams are experimental and disabled by default. Enable them in your settings.json or as an environment variable:
// ~/.claude/settings.json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Then tell Claude to create a team. Describe your task and the team structure you want in plain language:
# Example: describe the task and team structure
Create an agent team to build the user notification system.
Spawn three teammates:
- One for the backend API and database layer
- One for the frontend components and state management
- One for integration tests and error handling
The backend teammate should share API contracts with the frontend
teammate as they're finalized.Claude creates the team, spawns teammates, and distributes work. You can interact with any teammate directly using Shift+Up/Down in your terminal, or use split-pane mode with tmux for a side-by-side view of everyone's progress.
First Test: OAuth Implementation in Half the Time
Agent Teams landed in Claude Code 2.1.32 (early February 2026), and I wanted to test them on something real the day they shipped. I had a new project that needed GitHub and Google OAuth, so I figured this was a good first run.
With subagents, I would have planned this as sequential phases through my ai-workflow plugin: schema changes first, then OAuth handlers, then UI, then tests. Each phase runs in a fresh subagent context, which is great for isolation but means the UI phase starts blind to the exact response shapes the handler phase produced. The main agent summarizes what happened, but those summaries lose detail. I've seen subagents build client-side validation that doesn't match what the backend actually enforces, because the handoff lost that specificity.
With Agent Teams, I told the lead to spawn teammates for each layer and told them to share contracts as they worked. The teammate building OAuth handlers messaged the frontend teammate with the exact callback response shapes and session structures as it finalized them. The frontend teammate built its login and settings UI against actual contracts instead of guessing.
# What I told the lead:
Create a team to implement GitHub and Google OAuth.
This project already has passwordless OTP auth with
sessions in MongoDB.
Backend teammate: Add OAuth provider configs, callback
handlers, and account linking logic. Share the OAuth
response shapes and session structure with the frontend
teammate as you finalize them.
Frontend teammate: Add OAuth buttons to login and signup.
Add connect/disconnect controls in account settings.
Wait for the backend teammate's contracts before building
the data layer.
Test teammate: Write integration tests for the OAuth
flows. Watch both teammates and test against what they
actually built.It one-shot the implementation across multiple OAuth providers. Zero bugs. The frontend and backend matched on the first pass because the teammates coordinated the contracts themselves. With subagents, I'd typically spend time debugging mismatches between what the backend produced and what the frontend expected. That whole class of mismatch debugging just didn't happen.
Felt like roughly half the time my subagent workflow would have taken for the same feature. Some of that is the parallelism (teammates working simultaneously instead of sequential phases), but most of it was not having to fix handoff errors. No "oh, the backend returns an array here, not an object" debugging loops.
Where I Want to Try Agent Teams Next
After the OAuth test, I started thinking about what else this would be good for. I haven't tried any of these yet, but they're next on my list.
Debugging with competing hypotheses
This is the one I'm most curious about. With a single agent or sequential subagents, you tend to anchor on the first plausible theory and stop looking. If theory one seems reasonable, theory two never gets investigated properly.
Agent Teams let you spawn multiple teammates, each investigating a different hypothesis, and tell them to challenge each other's findings. Teammate A finds evidence for theory one, Teammate B points out why the timing doesn't match, Teammate C shares a finding that narrows the search. That kind of adversarial debugging can't happen with subagents because they can't see each other's work.
Next time I hit a bug with multiple plausible causes, I'm reaching for Agent Teams instead of stepping through hypotheses one at a time.
Parallel code review with cross-cutting feedback
I've run parallel code reviews with subagents before: one for security, one for performance, one for architecture. The problem is they produce three isolated reports. The main agent combines them, but nobody catches the cross-cutting concerns. A security finding might have performance implications that only the performance reviewer would notice.
With Agent Teams, reviewers could message each other directly. The security reviewer finds a missing rate limit, messages the performance reviewer to check whether adding one affects throughput. The architecture reviewer flags mixed concerns in a handler, and the security reviewer adds that the mixed concerns also make authorization harder to audit. The review becomes a conversation instead of three stapled-together reports.
Large-scale refactoring coordination
Refactors that touch shared interfaces are where subagent phase boundaries get awkward. If two phases both need to modify a shared type definition, you have to sequence them carefully, and the second phase still starts without full context of what the first one changed.
Agent Team teammates could negotiate shared interface changes in real time instead of relying on the orchestrator to guess the right sequencing. That's the theory, anyway. I want to test it on a real refactor before making claims.
When Subagents Are Still the Right Call
Agent Teams are not a replacement for subagents. They're more expensive (each teammate is a full Claude instance), more complex to manage, and overkill for work where coordination isn't needed.
Subagents remain the better choice for:
- Quick research tasks: "Read these 20 files and tell me how authentication works" doesn't need a team. A subagent returns a summary and keeps your main context clean.
- Independent phase execution: My ai-workflow plugin will continue using subagents for phase implementation. Phases are independent by design. No coordination needed means no benefit from Agent Teams.
- Focused verification: Running a security audit or performance check on a specific module is a single-agent job. The result matters, not an ongoing conversation.
- Token-conscious work: If you're watching costs, subagents are more efficient. Results get summarized back to the main context. Agent Teams keep full sessions running for each teammate.
The decision framework is straightforward: if your parallel workers need to talk to each other, use Agent Teams. If they just need to do their work and report back, use subagents.
Key Features Worth Knowing About
A few Agent Team capabilities that aren't obvious from the overview but proved useful in practice:
Delegate Mode
Without delegate mode, the lead sometimes starts implementing tasks itself instead of waiting for teammates. Press Shift+Tab to cycle into delegate mode, which restricts the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks. No direct code changes.
I think I will be using delegate mode almost exclusively. The lead's job is orchestration, not implementation. Letting it write code creates confusion about who owns what.
Plan Approval for Teammates
You can require teammates to plan before they start implementing. The teammate works in read-only plan mode until the lead approves their approach. If the lead rejects the plan, it sends feedback and the teammate revises.
This is valuable for risky changes. I used it when one teammate was responsible for database migration work. I wanted to see the migration plan before any schema changes happened.
# Require plan approval for sensitive work
Spawn a database teammate to handle the schema migration.
Require plan approval before making any changes.
Only approve plans that include rollback steps.Split Pane Mode
If you're running tmux or iTerm2, each teammate gets its own pane. You can see everyone's output simultaneously and click into any pane to interact directly. It's the closest thing to watching a team of developers work in parallel from your terminal.
In-process mode (the default) works in any terminal and uses Shift+Up/Down to cycle between teammates. Both work, but split panes make it easier to monitor progress across the team.
Limitations to Know About
Agent Teams carry the experimental label for a reason. These are the limitations:
- No session resumption for teammates: If you resume a session, in-process teammates are gone. The lead may try to message teammates that no longer exist. You'll need to spawn new ones.
- Task status can lag: Teammates sometimes forget to mark tasks as complete, which blocks dependent tasks. I've had to manually nudge teammates to update their task status.
- One team per session: You can't run multiple teams simultaneously from one lead. Clean up the current team before starting a new one.
- No nested teams: Teammates can't spawn their own teams. Only the lead manages the team structure.
- Token cost is real: Each teammate is a full Claude instance. A five-teammate debugging session burns through tokens fast. Use teams for work that genuinely benefits from coordination, not for everything.
None of these are dealbreakers. They're the rough edges you'd expect from a research preview. The core architecture works well: shared task list, peer-to-peer messaging, independent context windows. Those pieces are solid.
What I'm Building Next
I plan to expand my Claude Code plugin ecosystem to integrate Agent Teams where they make sense. The ai-workflow plugin's phase-based approach will keep using subagents for independent phase execution, since that's the right tool for the job. But I see real potential for Agent Teams in a few specific areas:
- Cross-phase verification: An Agent Team where one teammate implements a phase while another validates the previous phase's output. Real-time feedback instead of sequential verify-then-fix cycles.
- Complex refactoring coordination: Large-scale refactors where file ownership boundaries blur. Teammates can negotiate who handles shared interfaces instead of the orchestrator guessing.
- Research with adversarial review: Codebase analysis tasks where competing perspectives produce better results. One teammate proposes an architecture, another stress-tests it.
The ai-workflow plugin already handles the planning side well. Agent Teams extend what's possible during execution. Plan with ai-workflow, execute with Agent Teams when the work needs real collaboration. That's the combination I'm most excited about.
Subagents Report. Teammates Collaborate.
Agent Teams don't replace subagents. They fill a specific gap: parallel work where the workers need to communicate. If your subagents just need to complete tasks and return results, keep using subagents. They're cheaper, simpler, and fully sufficient.
But if you've ever wished your subagents could talk to each other, if you've been passing context back and forth through the main agent and losing detail in the summaries, if you've watched subagents duplicate work because they couldn't see what the other one decided, Agent Teams are the answer.
The experimental label is honest. Session resumption doesn't work for teammates yet, task status tracking can lag, and token costs are higher. But the core model, full Claude sessions communicating directly with each other through a shared task list, is sound. My first real test produced a zero-bug OAuth implementation in roughly half the time subagents would have taken. That's one data point, not a verdict, but it's a strong first impression.
Enable it with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, try it on your next cross-cutting feature, and see if the coordination overhead is worth it for your workflow. For me, it was.