Claude Code Agent Teams shipped in February 2026. Understanding the difference between subagents and teams — and when each costs 1.5x vs 7x more tokens — is the decision that determines whether multi-agent development helps or hurts your team.
For most of 2025, Claude Code's multi-agent story was straightforward: you could spawn subagents, they'd do work and report back, and you'd orchestrate them from the main session. Useful, but hub-and-spoke. The main agent was always the bottleneck.
In February 2026, that changed. Agent Teams shipped with Claude Opus 4.6, and the difference isn't incremental — it's architectural. Subagents can't talk to each other. Teammates can.
One environment variable enables the whole thing. And there are already over 100 community-built specialized agents ready to drop into any project.
Here's what actually changed, what it costs, and how to decide which model to use.
The Architecture Difference
The easiest way to understand the two models is to think about how information flows.
Subagents follow a hub-and-spoke pattern. You (the main agent) spawn a subagent, it does a task in its own context window, reports the result back, and terminates. No subagent can communicate with another subagent directly. If you spawn a test-runner and a code-reviewer in parallel, they operate in complete isolation — they can't share findings, can't block each other, can't hand off work.
This is fine for tasks that are genuinely independent: run a linter, generate a component, analyze a file. When those tasks don't need to coordinate, subagents are the right tool.
Agent Teams work differently. Each teammate runs in its own context window and can send messages directly to other teammates. A teammate can say: "I found a security issue in this module, flagging it for the security reviewer before we proceed." The security reviewer can respond before the code gets committed. No main agent needs to relay the message.
This peer-to-peer communication model unlocks workflows that subagents simply can't do: collaborative code review where one agent writes while another reviews in real time, multi-stage pipelines where Stage B blocks on Stage A's findings, or debugging sessions where a root-cause agent and a fix-implementation agent work the same problem from different angles simultaneously.
The tradeoff: teams cost significantly more. Understanding the cost model before enabling this feature will save you from surprises.
The Cost Model
This is the most important thing to internalize before choosing between subagents and teams.
Subagents run at approximately 1.5–2x the token cost of a single session. Each subagent has its own context window, so you pay for its context separately. But subagents are shorter-lived and more focused — they're spawned for a specific task, complete it, and terminate.
Agent Teams run at 3–7x the token cost of a single session. Each teammate maintains its own persistent context window for the full duration of the session. When teammates are in plan mode (recommended for complex work), they generate more output per turn as they reason through coordination. Seven teammates in an extended session against a large codebase isn't a theoretical number — it's a real cost scenario.
The decision rule:
• Embarrassingly parallel tasks with no inter-agent dependencies → subagents
• Tasks where agents need to share findings, block on each other, or hand off work mid-execution → teams
• Teams of more than 4–5 agents → only when you can demonstrate the coordination value exceeds the 3–7x cost
Most use cases that feel like they need teams actually don't. Two agents running in parallel with no communication need? That's two subagents, not a team. Teams justify their cost when peer-to-peer communication changes the outcome.
How Subagents Are Defined
Both subagents and agent teammates are defined the same way: a Markdown file with YAML frontmatter. The frontmatter defines the metadata; the body becomes the system prompt.
``markdown
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after any code changes
to check security vulnerabilities, style consistency, and maintainability.
Invoke when files have been modified or new code has been written.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 20
You are a thorough code reviewer with a focus on security and maintainability.
When reviewing code:
Check for OWASP top 10 vulnerabilities
Verify error handling is complete
Flag any hardcoded credentials or sensitive data
Check that tests cover the happy path and at least one failure case
Return a structured report: PASS / NEEDS CHANGES / BLOCK, with specific line references.
`
Only name and description are required. The description field is critical — it tells the main agent when to delegate to this subagent. Write it as trigger conditions, not as a capability summary.
Storage locations:
• .claude/agents/ — project-specific subagents, checked into the repo
• ~/.claude/agents/ — personal subagents, available in every project
The model field accepts sonnet, opus, haiku, a full model ID, or inherit (default, uses the main session's model). Using haiku for lightweight tasks like linting or file searches reduces cost significantly on subagents you spawn frequently.
Try It Yourself
Enable Agent Teams
Add this to your shell profile or set it per-session:
`bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
`
Agent Teams supports 2–16 agents. Start with 2–3 until you understand how your use case maps to the cost model.
Create Your First Subagent
Create the directory and write the definition:
`bash
mkdir -p .claude/agents
`
`markdown
.claude/agents/test-runner.md
name: test-runner
description: Run the test suite and report failures. Invoke after any implementation
changes, before code is committed. Do not invoke during planning phases.
tools: Bash, Read
model: haiku
maxTurns: 10
Run the full test suite. Report: total tests, pass count, fail count, and
the exact error message for each failing test. Do not attempt to fix failures —
report only.
`
Claude will now automatically delegate test execution to this agent whenever the trigger conditions in the description match.
Browse 100+ Community Subagents
The awesome-claude-code-subagents repository has over 100 community-built agents covering security scanning, documentation generation, dependency auditing, performance profiling, and more. Most are drop-in: copy the .md file into .claude/agents/, review the system prompt, and it's active.
Review any community agent's system prompt before using it. The description field controls when Claude auto-invokes it — make sure the trigger conditions match your workflow.
Decision Framework: Subagent vs Team
Ask these questions before spawning:
`
Do these agents need to share findings mid-task?
└─ YES → Agent Team
└─ NO → Are tasks independent and parallel?
└─ YES → Subagents
└─ NO → Sequential single-session (no multi-agent needed)
`
A code-generator and a test-runner that run after the generator completes? Sequential single-session. A code-generator and a real-time reviewer that flag issues before the generator commits a change? That's the case for a team.
Scope Subagents With maxTurns
Without maxTurns, a subagent can run indefinitely. For automated workflows, always set it:
`yaml
maxTurns: 15 # stops after 15 turns regardless of task completion
`
Combine this with specific tool lists to prevent a focused agent from expanding its scope unexpectedly:
`yaml
tools: Read, Grep, Glob # read-only — this agent cannot modify files
`
What Changes in Practice
The most immediate impact of subagents isn't teams — it's the auto-invocation behavior. Once you have agents in .claude/agents/`, Claude reads their descriptions at the start of every session. When the conditions match, it delegates automatically. You don't have to remember to run the linter or trigger the security scan; the agent fires when its trigger conditions are met.
This changes how CLAUDE.md needs to be written. Instead of putting "always run tests after changes" in the root instructions (which Claude must remember and apply manually), you put it in the subagent description ("Invoke after any implementation changes, before code is committed") and the trigger becomes structural rather than remembered.
The agent team feature extends this to multi-agent coordination. But for most teams getting started, the single-agent auto-invocation pattern has the highest ROI and the lowest complexity cost.
Start with subagents. Add a test-runner. Add a reviewer. Understand what auto-invocation actually does to your workflow. Agent Teams will be there when you genuinely need peer-to-peer communication — and you'll know you need it when you find yourself manually relaying information between two subagents.
The Practical Limit
Agent Teams supports up to 16 agents. That's a ceiling, not a target. The teams that work well in practice are 2–4 agents with tightly defined scopes and clear communication protocols.
The biggest failure mode isn't technical — it's over-coordination. When agents can talk to each other, it's tempting to build workflows where they talk constantly. Agents that check in with each other after every action, that ask for approvals mid-task, that generate inter-agent messages as a side effect of normal operations — these consume the 3–7x token cost without delivering 3–7x value.
Design for the minimum coordination needed. Define what each agent is responsible for and what triggers a cross-agent message. Peer-to-peer communication is the feature; discipline about when to use it is the practice.
The env var is one line. The judgment about which architecture your task actually needs takes longer to develop — but it's the decision that determines whether multi-agent development compounds your team's output or your API bill.