Agent Teams

Agent Teams

Coordinate multiple Claude Code instances as a team with shared task lists, inter-agent messaging, and independent context windows. Fundamentally different from subagents (Task tool): teammates communicate directly with each other, not just back to the caller.

When to Use Agent Teams vs Subagents

Does the work require inter-agent communication?
├── No → Use subagents (Task tool)
│   ├── Focused tasks where only the result matters
│   ├── Research/verification that reports back
│   └── Lower token cost (results summarized to main context)
└── Yes → Use Agent Teams
    ├── Teammates need to share findings mid-task
    ├── Adversarial debate / competing hypotheses
    ├── Self-organizing work from shared task list
    └── Complex coordination across 3+ parallel workers

How many parallel workers?
├── 1-3 independent tasks → Subagents (less overhead)
├── 3-5 coordinating workers → Agent Teams
└── 5+ workers → Agent Teams with delegate mode

Best use cases:

• Research + review from multiple perspectives simultaneously
• Multi-module features where teammates own different files
• Debugging with competing hypotheses (adversarial investigation)
• Cross-layer coordination (frontend, backend, tests)

Avoid when:

• Sequential tasks with many dependencies
• Same-file edits (causes overwrites)
• Simple focused work (coordination overhead not worth it)
• Routine tasks (single session more cost-effective)

Environment Setup

Enable Agent Teams (experimental, disabled by default):

// settings.json (user or project level)
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or set in shell: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Tool Architecture

Agent Teams use four distinct tools (not a single "TeammateTool"):

SendMessage Types

Critical: Plain text output is NOT visible to teammates. Agents MUST use SendMessage for all inter-agent communication.

Usage notes:

• Prefer message over broadcast — broadcast creates N messages for N teammates
• Messages delivered automatically to recipient inboxes (no polling)
• Idle notifications sent automatically when teammates finish
• Only the lead should run TeamDelete — teammate context may not resolve correctly

Spawning Teammates

Method 1: Natural language — Tell Claude to create a team and describe structure:

Create an agent team to review this PR. Spawn three reviewers:
- One focused on security
- One checking performance
- One validating test coverage

Method 2: Task tool with team parameters:

Task({
  team_name: "my-team",
  name: "worker-1",
  subagent_type: "general-purpose",
  prompt: "Review src/auth/ for security vulnerabilities...",
  model: "sonnet",
  run_in_background: true
})

Teammate receives on spawn:

• Same project context as regular session (CLAUDE.md, MCP servers, skills)
• The spawn prompt from the lead
• Does NOT inherit lead's conversation history

Built-in agent types for teammates:

Model selection: Use Sonnet for most teammates (cost-effective). Reserve Opus for leads or complex reasoning tasks. Specify via model parameter or natural language ("Use Sonnet for each teammate").

Spawn Backends

Controls how teammates display. Set via teammateMode in settings.json or --teammate-mode CLI flag.

// settings.json
{ "teammateMode": "in-process" }

# CLI override for single session
claude --teammate-mode in-process

Auto-detection logic:

1. $TMUX env var set → use tmux split panes
2. $ITERM_SESSION_ID set + it2 available → use iTerm2
3. which tmux succeeds → use tmux
4. Fallback → in-process

In-process navigation:

• Shift+Up/Down → select teammate
• Enter → view teammate's session
• Escape → interrupt teammate's current turn
• Ctrl+T → toggle task list

Split-pane navigation:

• Click into pane to interact directly
• Each teammate has full terminal view

Communication Patterns

Direct message (type: "message"): Send to one specific teammate via SendMessage. Use for targeted instructions, follow-ups, or redirecting approach.

Broadcast (type: "broadcast"): Send to all teammates simultaneously via SendMessage. Use sparingly — costs scale with team size. Good for: announcing shared decisions, requesting status updates.

Automatic delivery: Messages arrive at recipients automatically. Lead does not need to poll for updates.

Idle notifications: When a teammate finishes and stops, it automatically notifies the lead.

Message type schemas: See assets/message-formats.yml

Task Coordination

The shared task list coordinates work across the team. All agents see task status and can claim available work.

Task lifecycle: pending → in_progress → completed

Assignment patterns:

• Lead assigns explicitly ("Give task 3 to the security reviewer")
• Self-claim: after finishing a task, teammate picks next unassigned, unblocked task

Dependencies:

• Express with blockedBy field (array of task IDs)
• Auto-unblock: when blocking task completes, blocked tasks become available
• Enables sequential pipelines without polling

File locking: Task claiming uses file locking to prevent race conditions when multiple teammates try to claim simultaneously.

Recommended task sizing:

• 5-6 tasks per teammate for steady throughput
• Self-contained units producing clear deliverables
• Avoid: tasks too small (overhead > benefit) or too large (risk of wasted effort)

Delegate Mode

Restricts the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks. Prevents lead from implementing tasks itself.

Enable: Press Shift+Tab to cycle into delegate mode after starting a team.

When to use:

• Lead keeps implementing tasks instead of waiting for teammates
• You want pure orchestration (break down work, assign, synthesize)
• Large teams where lead should focus on coordination

Known bug: Teammates spawned AFTER entering delegate mode inherit restricted tool access (lose Read, Write, Edit, Bash, Glob, Grep). Workaround: Spawn all teammates BEFORE pressing Shift+Tab.

When to skip:

• Small teams where lead can contribute implementation
• Lead needs to do synthesis work requiring file edits

Plan Approval Workflow

Require teammates to plan before implementing. Teammate works in read-only plan mode until lead approves.

Spawn with plan approval:

Spawn an architect teammate to refactor the auth module.
Require plan approval before they make any changes.

The planModeRequired field in team config controls this per-member.

Workflow:

1. Teammate spawned with planModeRequired: true
2. Teammate explores codebase, creates plan
3. Teammate sends plan_approval_request to lead
4. Lead reviews plan:
   ├── approvePlan → teammate exits plan mode, begins implementation
   └── rejectPlan(feedback) → teammate stays in plan mode, revises
5. Cycle repeats until approved

Influence approval criteria via prompt:

Only approve plans that include test coverage.
Reject plans that modify the database schema.

File Conflict Avoidance

Two teammates editing the same file causes overwrites. Prevent this by assigning file ownership:

- teammate-1: owns src/api/ files
- teammate-2: owns src/ui/ files
- teammate-3: owns tests/ files

Anti-pattern: Multiple teammates modifying shared config files, package.json, or migration files simultaneously.

Mitigation: Use task dependencies to serialize edits to shared files.

Hooks Integration

Two hook events for enforcing quality gates in agent teams:

TeammateIdle

Fires when a teammate is about to go idle after finishing its turn.

• Exit 0 → allow idle
• Exit 2 → keep working (stderr fed back as feedback to teammate)
• No matcher support (fires on every occurrence)
• Input includes: teammate_name, team_name

TaskCompleted

Fires when a task is being marked as completed (via TaskUpdate or when teammate finishes with in-progress tasks).

• Exit 0 → allow completion
• Exit 2 → prevent completion (stderr fed back as feedback)
• No matcher support (fires on every occurrence)
• Input includes: task_id, task_subject, task_description, teammate_name, team_name

TeammateIdle: command hooks only (no prompt/agent hooks). TaskCompleted: supports command, prompt, and agent handler types.

See assets/hook-examples.yml for configuration examples.

Graceful Shutdown

Shutdown sequence:

1. Lead sends requestShutdown to each teammate
2. Teammate receives request:
   ├── approveShutdown → finishes current request/tool call, terminates
   └── rejectShutdown(reason) → continues working
3. Wait for all teammates to terminate
4. Lead calls cleanup
   ├── If active teammates remain → cleanup fails
   └── If all terminated → removes team config + task directories

Important:

• Shutdown can be slow — teammates finish current request before terminating
• Always use lead for cleanup (not teammates)
• For orphaned tmux sessions: tmux ls && tmux kill-session -t <name>

Permissions

• Teammates start with lead's permission settings
• If lead uses --dangerously-skip-permissions, all teammates do too
• Can change individual teammate modes after spawning
• Cannot set per-teammate modes at spawn time
• Pre-approve common operations in permission settings to reduce prompt interruptions

File Structure

~/.claude/
├── teams/
│   └── {team-name}/
│       ├── config.json          # team config (members, lead, settings)
│       └── inboxes/
│           └── {agent}.json     # per-agent message inbox
└── tasks/
    └── {team-name}/
        ├── 1.json               # task files (auto-incremented IDs)
        ├── 2.json
        └── N.json

See assets/team-config-schema.yml for full schemas.

Known Limitations

Error Handling

Orchestration Patterns

See references/orchestration-patterns.md for 4 detailed patterns:

1. Parallel Review — Multiple specialists review simultaneously with distinct lenses
2. Competing Hypotheses — Adversarial investigation prevents anchoring bias
3. Multi-Module Feature — File ownership + task dependencies for coordinated implementation
4. Research Pipeline — Research phase feeds into plan-approved implementation