Claude Code Agent Teams vs Subagents: When to Use Which (From Someone Who Uses Both Daily)

Summary

The core question is not "which is better." It is "do your agents need to talk to each other?" If yes, use agent teams. If no, subagents are cheaper and simpler. Everything else is detail.

The Three Approaches to Parallel Work in Claude Code

Claude Code supports three distinct patterns for running work in parallel. They differ in communication model, cost, and how much control you retain as the human operator.

Subagents: The Agent Tool

Subagents are spawned within a single Claude Code session using the Agent tool. Each subagent gets its own context window, runs its task, and returns a summary to the parent. The parent is the only agent that sees all results. Subagents cannot message each other.

How Subagents Work

• Parent agent calls the Agent tool with a prompt and (optionally) a custom system prompt
• Subagent gets its own context window, separate from the parent
• Subagent has access to the same tools (file read, write, grep, bash)
• When finished, the subagent returns a text summary to the parent
• Parent receives the summary and continues its work

# Parent agent spawns 5 subagents in parallel
# Each researches a different topic and returns a summary

Agent(prompt="Research the Stripe SDK payment intent flow")
Agent(prompt="Research the Plaid link token exchange pattern")
Agent(prompt="Find all existing payment-related files in src/")
Agent(prompt="Check the database schema for payment tables")
Agent(prompt="Read the current test coverage for billing/")

# All 5 run simultaneously
# Each gets its own context window (no cross-pollination)
# Parent receives 5 summaries, synthesizes, and acts

When Subagents Win

When Subagents Break Down

The parent bottleneck becomes painful when agents need to share intermediate results. If subagent A discovers a type definition that subagent B needs, the information must flow: A returns summary to parent, parent parses it, parent spawns B (or re-prompts B) with that context. With 8 agents, this coordination overhead dominates the parent's context window.

Agent Teams: TeamCreate + SendMessage

Agent teams are independent Claude Code sessions that coordinate through a shared task list and direct messaging. Each teammate is a full session with its own context window, tool access, and permissions. The team lead orchestrates, but teammates can message each other without going through the lead.

How Agent Teams Work

• Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• Team lead calls TeamCreate to set up the team directory and config
• Lead spawns teammates, each as an independent Claude Code process
• Teammates share a task list at ~/.claude/tasks/{team-name}/
• Any agent can message any other agent via SendMessage
• SendMessage supports direct messages, broadcasts, shutdown requests, and plan approvals

# Team lead creates the team
TeamCreate(name="payment-feature")

# Spawn specialized teammates
# Each is a FULL Claude Code session with its own context

# API teammate: builds the payment endpoints
# UI teammate: builds the payment form
# Test teammate: writes integration tests

# The coordination difference:
# API teammate finishes type definitions →
#   SendMessage(to="ui-teammate", "PaymentIntent types are at src/types/payment.ts")
# UI teammate picks it up immediately, no round-trip through the lead

# Test teammate asks API teammate directly:
#   SendMessage(to="api-teammate", "Can you start the dev server on port 3001?")
# API teammate responds, test teammate proceeds

# Shared task list tracks dependencies:
# Task "Build UI" is blocked by "Define API types"
# When API teammate marks types complete, UI task unblocks automatically

When Agent Teams Win

The Cost Reality

Every teammate is a full Claude Code session. A 3-agent team uses roughly 3-4x the tokens of doing the same work sequentially in one session. With 8 agents, that multiplies further. Anthropic built their 100,000-line C compiler with 2,000 sessions at $20,000 in API cost. For most teams, the practical sweet spot is 3-5 teammates.

Manual Panes: You Are the Coordinator

No coordination layer. No shared task list. No SendMessage. You open 6 terminal panes, start a Claude Code session in each, and relay information between them yourself. This is the approach that experienced power users often prefer.

The Setup

• iTerm2 splits, tmux panes, or multiple terminal windows
• Each pane is an independent Claude Code session
• You monitor all panes and copy-paste between them as needed
• No token overhead for coordination, you do it with your eyes and clipboard

# Terminal layout on ultrawide monitor:
# ┌─────────┬─────────┬─────────┐
# │ Pane 1  │ Pane 2  │ Pane 3  │
# │ Backend │ Frontend│ Tests   │
# ├─────────┼─────────┼─────────┤
# │ Pane 4  │ Pane 5  │ Pane 6  │
# │ Docs    │ DevOps  │ Review  │
# └─────────┴─────────┴─────────┘
#
# Pane 1 finishes the API endpoint →
# You see it, copy the route path, paste into Pane 2's prompt
# Pane 3 watches both and you feed it test subjects
#
# No tokens spent on coordination
# No waiting for SendMessage delivery
# Maximum situational awareness

When Manual Panes Win

Manual panes win when you value control over automation. You see every agent's output in real time. You decide what information to share and when. There is no risk of an agent team lead making a bad coordination decision that cascades through the whole team. The tradeoff: your attention is the bottleneck. Beyond 6-8 panes, most people lose track.

Decision Framework

After months of using all three approaches daily, the decision reduces to two questions.

The Two Questions

Cost Comparison: Real Token Numbers

Token costs vary by task complexity, but the ratios are consistent. Here are representative numbers from production usage.

Why Agent Teams Cost More

Each teammate maintains a full context window. A subagent gets a scoped prompt and returns a summary. A teammate persists for the entire team session, accumulating context as it receives messages from other agents, reads shared task updates, and processes its own work. The coordination messages alone can add 30-50% overhead.

Cost Optimization Strategies

• Mix models: Sonnet 4.6 for workers, Opus 4.6 for the lead. Cuts cost 40-50% with minimal quality loss.
• Scope tasks tightly: A teammate that finishes early still holds its context window open. Give each agent exactly one well-defined task.
• Use subagents within teams: A teammate can spawn its own subagents for sub-tasks. Use teams for coordination, subagents for execution within each teammate.
• Plan first: Run plan mode before committing tokens to a team. A 5-minute planning pass can prevent a 30-minute wasted team run.

Real Examples from Production

Example 1: SEO Content Pipeline (Agent Teams)

Morph's SEO pipeline runs 22 writer agents in a team. A trend-scout agent identifies keywords. The team lead distributes topics via SendMessage. Each writer agent produces a complete page (React component, metadata, structured data) and commits independently. Writers share internal link targets with siblings so pages cross-reference each other.

This would not work with subagents. The cross-linking requirement means writers need to know what URLs other writers are creating. With subagents, the parent would need to track 22 pages' worth of URLs and relay them, which would overflow its context window.

Example 2: Research Pipeline (Subagents)

Before writing each SEO page, the pipeline spawns 5-8 research subagents. Each searches for different aspects of the topic: competitor content, community discussions, documentation, benchmarks. Each subagent returns a 200-300 word summary. The parent synthesizes these into a research brief that gets forwarded to the writer agent.

Subagents are correct here because each research query is independent. The subagent searching Reddit does not need to know what the subagent reading documentation found. The parent handles synthesis.

Example 3: Multi-Issue Debugging (Manual Panes)

When facing 4-6 unrelated bugs across different parts of the codebase, manual panes win. Each pane gets one bug. You watch all of them, intervene when one gets stuck, and can quickly redirect an agent that goes off track. No coordination overhead because the bugs are independent.

# Ask yourself:
#
# 1. Are the tasks independent?
#    YES → Subagents (cheapest) or Manual Panes (most control)
#    NO  → Agent Teams (coordination required)
#
# 2. How many parallel tasks?
#    1-3  → Subagents
#    4-8  → Manual Panes or Agent Teams
#    8+   → Agent Teams (you can't watch 8+ panes)
#
# 3. Do agents need real-time shared state?
#    YES → Agent Teams (SendMessage + shared tasks)
#    NO  → Subagents
#
# 4. Is cost a concern?
#    YES → Subagents (1.75x) > Panes (2x) > Teams (3.5x)
#    NO  → Pick based on coordination needs

Common Mistakes

Mistake 1: Using Agent Teams for Independent Tasks

If your agents do not need to talk to each other, agent teams waste tokens on coordination infrastructure. The shared task list, message routing, and team config all consume context. For 5 independent research tasks, subagents cost 1.75x baseline. An agent team doing the same work costs 3.5x. You pay double for coordination you do not use.

Mistake 2: Using Subagents When Coordination Is Needed

The opposite mistake is equally expensive. If you use subagents for a cross-layer feature, the parent becomes a bottleneck. It receives results from the API subagent, then must re-prompt the UI subagent with that context, then feed test results back to both. The parent's context window fills with relay traffic instead of actual work.

Mistake 3: Too Many Agents

More agents does not mean faster results. Agent teams have diminishing returns past 5-6 teammates because coordination overhead grows with team size. Each additional agent adds messages to every other agent's context window. Anthropic's C compiler project used 16 agents, but that was a 100,000-line project over two weeks. For a typical feature, 3-5 agents is the sweet spot.

Mistake 4: Not Planning First

Starting a 5-agent team without a clear task breakdown wastes the first 10-15 minutes of every agent's time on discovery. Run plan mode first. Define what each agent will do. Then spawn the team with clear assignments.

Frequently Asked Questions

What is the difference between agent teams and subagents in Claude Code?

Subagents (the Agent tool) run within a single session and report results to the parent. They cannot message each other. Agent teams (TeamCreate + SendMessage) are independent Claude Code sessions that message each other directly, share a task list, and self-coordinate. Subagents are isolated workers. Agent teams are a coordinated group.

When should I use agent teams instead of subagents?

Use agent teams when agents need to share discoveries mid-task, when you have 8+ parallel tasks, or when one agent's output affects another agent's approach. Use subagents for independent research, parallel file reads, or any work where each agent can finish without knowing what the others found.

How much do agent teams cost compared to subagents?

A 3-teammate agent team uses roughly 3-4x the tokens of a single session. Each teammate is a full Claude Code session with its own context window, costing approximately 5x per teammate versus a subagent. Subagents have smaller, focused context windows. For cost-sensitive work, use Sonnet 4.6 for worker agents and Opus 4.6 only for the team lead.

Can I use manual terminal panes instead of agent teams?

Yes. Manual panes (iTerm2 splits, tmux) give you maximum control with zero coordination overhead. You are the coordinator. This works well for 4-8 parallel tasks where you want to monitor each agent. The tradeoff: your attention is the bottleneck. Beyond 6-8 panes, most people lose track.

How do I enable agent teams in Claude Code?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your shell or settings.json. This unlocks TeamCreate, TaskCreate, TaskUpdate, TaskList, and SendMessage. Agent teams support 2-16 agents working on shared codebases. Released with Claude Opus 4.6 on February 5, 2026.

Can subagents within agent teams talk to teammates?

No. A subagent spawned by a teammate still follows subagent rules: it reports to its parent (the teammate), not to the team. But the teammate can relay findings to other teammates via SendMessage. This is a valid pattern: use subagents for execution within each teammate, agent teams for coordination between teammates.

What is the maximum number of agents in a team?

Agent teams support 2-16 teammates. In practice, diminishing returns start around 5-6 agents because coordination overhead grows quadratically with team size. Anthropic's 16-agent C compiler project is the upper bound of what has been demonstrated publicly.