🌻 prg.sh

Claude Code Agent Teams

Feb 09, 20266 min read

Agent teams are the third tier of Claude Code’s delegation hierarchy. Where subagents are isolated workers that report back to a parent, agent teams are fully independent Claude Code sessions that coordinate through a shared task list and message each other directly. Think of subagents as contractors you dispatch. Agent teams are a squad that self-organizes.

Shipped alongside Opus 4.6 in February 2026. Still experimental, gated behind a feature flag.

Why Teams of Agents?

Single agents degrade as context grows. Subagents help by isolating work, but they can only report back to the parent. Agent teams break that constraint: teammates share findings, challenge each other’s reasoning, and claim work autonomously from a shared queue. The architecture mirrors how real engineering teams operate.

Anthropic proved the concept by having 16 parallel Opus 4.6 instances build a 100,000-line C compiler in Rust over two weeks. It compiled Linux 6.9, QEMU, FFmpeg, SQLite, and ran Doom. Cost: $20,000 in tokens. The coordination mechanism was surprisingly simple: git-based task locking with no orchestration agent.

Architecture

ComponentRole
Team leadMain session that spawns teammates, assigns work, synthesizes results
TeammatesIndependent Claude instances with their own full context windows
Task listShared work queue with dependency tracking and file-locking claims
MailboxPeer-to-peer messaging system between all agents

Stored locally at ~/.claude/teams/{team-name}/config.json and ~/.claude/tasks/{team-name}/.

Seven Primitives

The entire system runs on these tools:

  1. TeamCreate - initialize team namespace and config
  2. TaskCreate - define work units as JSON files on disk
  3. TaskUpdate - claim tasks, mark complete, set dependencies
  4. TaskList - discover available work
  5. Task (with team_name) - spawn a new teammate into the team
  6. SendMessage - direct messages, broadcasts, shutdown requests, plan approvals
  7. TeamDelete - cleanup after completion

Tasks flow through three states: pending > in_progress > completed. File locking prevents double-claims when multiple teammates grab work simultaneously.

Enabling

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Then just describe your team in natural language:

Create a team with 3 teammates to review the auth module:
one on security, one on performance, one on test coverage.

Display Modes

  • In-process (default): all teammates in your terminal. Shift+Up/Down to navigate, Enter to view, Escape to interrupt, Ctrl+T for task list.
  • Split panes: each teammate gets its own tmux or iTerm2 pane. Requires tmux or iTerm2 with it2 CLI.

Set via "teammateMode": "in-process" or "tmux" in settings.json, or --teammate-mode flag.

Coordination Patterns

Competing hypotheses: spawn 5 investigators for a bug, each testing a different theory. Have them actively try to disprove each other. The theory that survives cross-examination is likely the root cause.

Parallel review: security, performance, and test coverage reviewers work the same PR simultaneously through different lenses. Lead synthesizes.

Cross-layer features: frontend, backend, and tests each owned by a different teammate. No file conflicts because each owns distinct paths.

Plan-then-execute: use plan mode (cheap) to design the approach, then hand the plan to a team for parallel execution (expensive but fast).

Delegate Mode

Press Shift+Tab to restrict the lead to coordination-only tools. Prevents the lead from implementing tasks itself instead of delegating. Useful when you want pure orchestration.

Plan Approval

For risky work, require teammates to plan before implementing:

Spawn an architect teammate to refactor authentication.
Require plan approval before they make changes.

Teammate stays read-only until the lead approves their plan. Rejected plans get feedback and resubmission.

Quality Gates via Hooks

Two hooks enforce standards:

  • TeammateIdle - runs when teammate is about to go idle. Exit code 2 sends feedback and keeps them working.
  • TaskCompleted - runs when task is being marked complete. Exit code 2 blocks completion with feedback.

Subagents vs Agent Teams

| Aspect | Subagents | Agent Teams | | ------------- | --------------------------------------- | --------------------------------------- | ----------- | | Communication | Report to parent only | Direct peer messaging | | Context | Own window, results summarized back | Own window, fully independent | | Coordination | Parent manages everything | Self-coordinate via shared task list | | Token cost | Lower (results summarized) | Higher (each teammate is full instance) | | Best for | Focused tasks where only result matters | Complex work needing discussion |

Use subagents when workers just need to report back. Use teams when they need to share findings, challenge each other, and self-organize.

Don’t sleep on the token cost

Each teammate requires a full context window. Solo session: ~200k tokens. Team of 3: ~800k tokens. Team of 5: ~1.2M+ tokens. The C compiler project burned 2B input tokens across 16 agents.

Mitigation strategies:

  • Use Sonnet for teammates, Opus for the lead
  • Plan cheaply first, execute in parallel second
  • Size tasks at 5-6 per teammate for optimal throughput
  • Kill the team as soon as work completes

When to Use

Strong fit:

  • Research and review with multiple perspectives
  • New modules where teammates own distinct files
  • Debugging with competing hypotheses
  • Cross-layer changes (frontend + backend + tests)

Poor fit:

  • Sequential tasks requiring handoff
  • Same-file edits (merge conflicts)
  • Simple tasks (coordination overhead kills you)
  • Tight budgets (token costs scale linearly with team size)

Limitations

  • Experimental - disabled by default, breaking changes possible
  • No session resumption for in-process teammates after /resume
  • Task status can lag - teammates sometimes forget to mark tasks complete
  • One team per session - clean up before starting another
  • No nested teams - teammates cannot spawn their own teams
  • Lead is fixed - can’t transfer leadership
  • Permissions propagate - all teammates inherit lead’s permission mode at spawn
  • Split panes need tmux or iTerm2 (not VS Code terminal, Windows Terminal, or Ghostty)

The C Compiler Proof Point

Anthropic’s most ambitious demonstration: 16 parallel Opus 4.6 instances built a clean-room C compiler in Rust.

  • 100,000 lines of Rust
  • Compiled Linux 6.9 kernel on x86, ARM, RISC-V
  • 99% pass rate on GCC torture tests
  • Coordination via git lock files, no orchestration agent

Key lesson: “Claude will work autonomously to solve whatever problem I give it. So it’s important that the task verifier is nearly perfect, otherwise Claude will solve the wrong problem.” Testing quality matters more than agent sophistication.

Community Tools

Sources

Graph View

Backlinks