Agent Teams vs Subagents: How Claude Code Evolves from Solo to Team Collaboration

Why Agent Teams?

Subagents can only report to the lead, preventing direct communication between teammates. This causes serial execution, lack of shared findings, and early termination after a single plausible explanation.

Limitations of Subagents

Subagents operate with a single context window and report results back to the lead. They cannot discuss findings, analogous to a manager assigning employees who cannot interact.

Parallel Collaboration Needs

Competing hypothesis investigation: Multiple possible causes for a crash (WebSocket, token expiry, message handling, memory leak, front‑end JS error). A single agent may stop at the first plausible cause (anchoring bias). Five agents can explore all hypotheses in parallel and challenge each other's conclusions.

Cross‑layer development coordination: Developing a feature spanning front‑end, back‑end, and tests benefits from three agents each focusing on one layer while sharing interface contracts.

Agent Teams Value Proposition

Team members can send messages directly to each other without routing through the lead.

Parallel execution: Multiple tasks run simultaneously.

Information sharing: Findings are instantly visible to all teammates.

Self‑coordination: A shared task list lets teammates claim work autonomously.

Direct interaction: Users can converse with any teammate without going through the lead.

Trade‑off: higher token cost because each teammate maintains its own context window.

How Agent Teams Works

Four core components:

Team Lead: The primary Claude Code session that creates the team, generates teammates, assigns initial tasks, and aggregates final results. It coordinates rather than micromanages.

Teammates: Independent Claude Code instances, each with its own context window. They do not inherit the lead’s conversation history and must be provided sufficient context at creation.

Task List: A shared list visible to all teammates. Tasks can be assigned by the lead or self‑claimed. Dependencies and file locks prevent conflicting edits.

Mailbox: Supports message (direct to a specific teammate) and broadcast (to all teammates). Completed tasks automatically notify the lead.

Communication topology is a mesh:

Lead ↔ Teammate 1 ↔ Teammate 2 ↔ Teammate 3
               ↕           ↕
        Shared task list + Mailbox

Subagents use a star topology where each sub‑agent only talks to the lead.

Display Modes

In‑process (default): All teammates run inside the lead’s terminal. Use Shift+Down to cycle through each teammate’s output. No extra tools required, but only one teammate is visible at a time.

Split panes: Each teammate gets its own terminal pane, allowing simultaneous observation. Requires tmux or iTerm2; not supported in VS Code integrated terminal, Windows Terminal, or Ghostty.

Enabling Agent Teams

Agent Teams is experimental and must be enabled manually. Add the following to .claude/settings.json in the project root:

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

Or set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

First Agent Team Example

Prompt:

I’m designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil’s advocate.

Execution steps:

Lead creates a team with a shared task list.

Three teammates (UX researcher, architecture reviewer, devil’s advocate) are generated.

Teammates explore the problem in parallel.

Lead aggregates the findings.

The team is cleaned up.

Interacting with Teammates

In‑process: Use Shift+Down to cycle and send messages directly.

Split panes: Interact with any teammate’s pane directly.

Typical Use Cases

Parallel code review: Spawn three reviewers (security, performance, test coverage) to examine a PR concurrently. Lead consolidates the three reports.

Competing hypothesis investigation: Spawn five teammates, each probing a different possible cause, and have them challenge each other's conclusions. The surviving hypothesis is most likely the root cause.

Cross‑layer coordinated development: Assign frontend, backend, and test teammates to work on their respective layers while sharing a task list to avoid conflicts.

Best‑Practice Checklist (from official documentation)

Provide sufficient context when spawning teammates because they do not inherit the lead’s history.

Choose team size based on task complexity: simple (2‑3), medium (3‑5, recommended start), complex (5‑7), very complex (multi‑stage splitting).

Start with read‑only tasks (code review, bug investigation, documentation research) before moving to write operations.

Let the lead wait for teammates; the lead should not perform work itself.

Known Limitations

In‑process teammates cannot be resumed with /resume or /rewind.

Each session can manage only one team; nested teams are not supported.

The lead is fixed and cannot be promoted to a teammate.

Permissions are set at generation time; they cannot be changed per teammate.

Choosing Subagents vs. Agent Teams

Decision summary:

Sequential tasks, only final result needed, or limited budget → Subagents (lower token cost).

Parallel exploration, competing hypotheses, or cross‑layer coordination → Agent Teams (direct teammate communication).

Token Cost and Optimization

Agent Teams incurs roughly 3× the token cost of Subagents for simple research and code review, and up to 5× for competing‑hypothesis investigations.

Adjust team size dynamically (start with 3, add or remove as needed).

Select appropriate model (e.g., Haiku for simple tasks, Sonnet/Opus for complex work).

Provide precise but not excessive context when spawning teammates.

Close idle teammates promptly to reduce consumption.

Common Troubleshooting

Teammates not visible: In‑process mode may hide running teammates; ensure tmux is installed for split panes.

Excessive permission prompts: Pre‑approve common actions in settings.json or adjust permission settings.

Teammate errors: Use Shift+Down (in‑process) or interact directly (split panes) to give additional instructions or replace the failing teammate.

Orphaned tmux sessions: List sessions with tmux ls and terminate with tmux kill-session -t <session-name>.

Conclusion

Claude Agent Teams enables true multi‑agent collaboration by allowing peers to communicate directly, share a task list, and self‑coordinate. It is well‑suited for parallel exploration, hypothesis testing, and cross‑layer development, while incurring higher token costs and remaining experimental.

Relevant resources:

Claude Code documentation: https://code.claude.com/docs/en/agent-teams

Agent Teams comparison image: https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png