Claude Code Agent Teams: The New Frontier of Multi-Agent Collaboration

Recommended Prerequisites

This article covers Claude Code’s experimental Agent Teams feature. If you’re not yet familiar with the basics of Subagents, consider reading these articles first:

• How to Effectively Use Claude Code Subagents
• Claude Code Subagents and Plan Mode: The New Era of Intelligent Collaboration

Have you ever faced this scenario? A large refactoring task where you need to simultaneously analyze security implications, performance impact, and test coverage — but a single Agent can only focus on one thing at a time. While Subagents can divide work, they operate like a “relay race”: completing tasks and throwing results back, unable to communicate directly with each other.

If Subagents represent “division of labor,” then Agent Teams represent true “collaboration.”

Claude Code has introduced the experimental Agent Teams feature, enabling multiple Claude Code instances to form a team with a shared task list, real-time inter-agent messaging, and centralized team management. This is no longer just about farming out work and collecting results — it’s about having AI assistants collaborate like a real development team, discussing ideas, challenging each other’s perspectives, and autonomously coordinating work.

⚠️ Experimental Feature Notice: Agent Teams is currently experimental and disabled by default. Manual activation is required before use, and there are known limitations.

Agent Teams Overview: From Solo to Team

What Are Agent Teams?

The core architecture of Agent Teams is straightforward: one Team Lead plus multiple Teammates.

• Team Lead: Your main Claude Code session, responsible for creating the team, assigning tasks, coordinating work, and synthesizing results
• Teammates: Independent Claude Code instances, each with their own full context window, capable of working independently
• Task List: A shared list of work items that all members can view and claim
• Mailbox: A messaging system enabling direct communication between members

The key difference from Subagents: Teammates can talk directly to each other. This isn’t a hub-and-spoke architecture — it’s a mesh communication model.

Agent Teams Architecture

graph TB
    U[User] --> L[Team Lead<br/>Main Claude Code Session]

    L --> T1[Teammate 1<br/>Security Review]
    L --> T2[Teammate 2<br/>Performance Analysis]
    L --> T3[Teammate 3<br/>Test Coverage]

    T1 <--> T2
    T2 <--> T3
    T1 <--> T3

    L --- TL[Shared Task List]
    L --- MB[Mailbox]
    L --- CF[Team Config]

    TL --- T1
    TL --- T2
    TL --- T3

    subgraph Project Context
        CL[CLAUDE.md]
        MCP[MCP Servers]
        SK[Skills]
    end

    CL --> T1
    CL --> T2
    CL --> T3

    style U fill:#e1f5fe
    style L fill:#e1f5fe
    style T1 fill:#fff3e0
    style T2 fill:#fff3e0
    style T3 fill:#fff3e0
    style TL fill:#c8e6c9
    style MB fill:#c8e6c9
    style CF fill:#c8e6c9

Agent Teams vs Subagents: Key Differences

In a nutshell: Use Subagents when workers just need to “complete and report.” Use Agent Teams when they need to “share findings, challenge perspectives, and coordinate autonomously.”

graph LR
    subgraph Subagents Model
        MA[Main Agent] --> SA1[Subagent 1]
        MA --> SA2[Subagent 2]
        MA --> SA3[Subagent 3]
        SA1 -->|Report Results| MA
        SA2 -->|Report Results| MA
        SA3 -->|Report Results| MA
    end

    subgraph Agent Teams Model
        TL[Team Lead] --> TM1[Teammate 1]
        TL --> TM2[Teammate 2]
        TL --> TM3[Teammate 3]
        TM1 <-->|Direct Messaging| TM2
        TM2 <-->|Direct Messaging| TM3
        TM1 <-->|Direct Messaging| TM3
    end

    style MA fill:#e1f5fe
    style SA1 fill:#fff3e0
    style SA2 fill:#fff3e0
    style SA3 fill:#fff3e0
    style TL fill:#e1f5fe
    style TM1 fill:#c8e6c9
    style TM2 fill:#c8e6c9
    style TM3 fill:#c8e6c9

Enabling and Basic Setup

Enable Agent Teams

Agent Teams are disabled by default. You can enable them in two ways:

Option 1: settings.json

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

Option 2: Environment Variable

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Start Your First Agent Team

Once enabled, simply tell Claude in natural language to create a team:

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.

Claude will automatically:

1. Create the team and shared task list
2. Spawn independent Teammates for each role
3. Have Teammates explore the problem
4. Synthesize all findings
5. Clean up team resources when finished

You don’t even need to ask — if Claude determines your task would benefit from parallel work, it may proactively suggest creating an Agent Team, proceeding after your confirmation.

Team Data Storage

Agent Teams data is stored locally:

~/.claude/teams/{team-name}/config.json    # Team config (member names, IDs, types)
~/.claude/tasks/{team-name}/               # Shared task list

The team config contains a members array recording each Teammate’s name, agent ID, and type. Teammates can read this file to discover other team members.

Display Modes Explained

In-process Mode

All Teammates run inside your main terminal. This is the default mode and requires no additional tool installation.

Keyboard Controls:

Split Panes Mode

Each Teammate gets its own terminal pane. You can see everyone’s output simultaneously and click into a pane to interact directly.

Prerequisites:

• tmux: Install via your system’s package manager (brew install tmux)
• iTerm2: Install the it2 CLI and enable the Python API in iTerm2 → Settings → General → Magic

💡 Tip: tmux works best on macOS. Using tmux -CC in iTerm2 is the recommended entry point.

Display Mode Comparison

Configure Display Mode

settings.json configuration:

{
  "teammateMode": "in-process"
}

Available values:

• "auto" (default): Uses split panes if already inside a tmux session, otherwise in-process
• "in-process": Force in-process mode
• "tmux": Enable split-pane mode, auto-detecting tmux or iTerm2

CLI flag override (single session):

claude --teammate-mode in-process

Team Management and Coordination

Specify Teammates and Models

Claude automatically decides the number of Teammates based on your task, but you can specify exactly what you want:

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Task Management System

The shared task list is the core of team coordination. Tasks have three states and a dependency management mechanism:

Three Task States:

Dependency Management: Tasks can depend on other tasks. When a Teammate completes a task, dependent tasks are automatically unblocked. Tasks with unresolved dependencies cannot be claimed.

Task Assignment Methods:

• Lead assigns: Tell the Lead which task to give to which Teammate
• Auto-claim: After completing their current task, Teammates automatically claim the next unassigned, unblocked task

File Locking for Conflict Prevention: When multiple Teammates attempt to claim the same task simultaneously, the system uses file locking to prevent race conditions.

Talk to Teammates Directly

Each Teammate is a full, independent Claude Code session. You can message any Teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.

In-process mode:

1. Shift+Up/Down to select a Teammate
2. Type to send a message
3. Enter to view the Teammate’s session details
4. Escape to interrupt current turn
5. Ctrl+T to toggle task list

Split Panes mode:

• Click directly into a Teammate’s pane to interact
• Each Teammate has its own full terminal view

Plan Approval Mechanism

For complex or high-risk tasks, you can require Teammates to plan before implementing:

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

graph TD
    A[Teammate Enters Read-Only Plan Mode] --> B[Analyze Code and Draft Plan]
    B --> C[Submit Plan Approval Request to Lead]
    C --> D{Lead Reviews Plan}

    D -->|Approved| E[Teammate Exits Plan Mode]
    E --> F[Begin Implementation]

    D -->|Rejected| G[Lead Provides Revision Feedback]
    G --> H[Teammate Revises Plan Based on Feedback]
    H --> C

    style A fill:#e1f5fe
    style D fill:#fff3e0
    style F fill:#c8e6c9
    style G fill:#ffcdd2

Influencing the Lead’s approval decisions: Add criteria to your prompt:

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

The Lead makes approval decisions autonomously based on these criteria.

Delegate Mode: Coordination-Only Mode

By default, the Lead sometimes “can’t resist” implementing tasks itself instead of waiting for Teammates. Delegate Mode restricts the Lead to coordination-only tools: spawning Teammates, sending messages, shutting down Teammates, and managing tasks.

How to enable: Start a team first, then press Shift+Tab to cycle into delegate mode.

When to use:

• You want the Lead focused purely on “breaking down work, assigning tasks, synthesizing results”
• Prevent the Lead from writing code while neglecting coordination duties
• Large teams (4+ Teammates) where coordination itself is a full-time job

Team Lifecycle Management

Shut down a single Teammate:

Ask the researcher teammate to shut down

The Lead sends a shutdown request. The Teammate can approve (exit gracefully) or reject (with an explanation).

Clean up the entire team:

Clean up the team

⚠️ Important: Always clean up through the Lead. Shut down all Teammates before running team cleanup. Teammates should not run cleanup themselves, as their team context may not resolve correctly, potentially leaving resources in an inconsistent state.

Communication Architecture Deep Dive

Mailbox Messaging System

Agent Teams communication works through the Mailbox system, supporting two message types:

💡 Note: Broadcast token costs scale proportionally with team size. Use sparingly.

Automatic Delivery Mechanisms:

• Messages sent by Teammates are delivered automatically to recipients; the Lead doesn’t need to relay manually
• When a Teammate finishes and stops, it automatically notifies the Lead
• All agents can view task status and claim available work

Context and Permissions

Context Loading:

• Each Teammate loads the same project context as a regular session when spawned: CLAUDE.md, MCP servers, Skills
• Teammates receive the Lead’s spawn prompt
• The Lead’s conversation history is not passed to Teammates

Permission Inheritance:

• Teammates start with the Lead’s permission settings
• If the Lead uses --dangerously-skip-permissions, all Teammates do too
• Individual Teammate permission modes can be adjusted after spawning
• Per-teammate modes cannot be set at spawn time

Complete Workflow

sequenceDiagram
    participant U as User
    participant L as Team Lead
    participant T1 as Teammate 1
    participant T2 as Teammate 2
    participant TL as Shared Task List

    U->>L: Describe task requirements
    L->>L: Analyze task, decide team structure

    L->>T1: Spawn Teammate 1 (with spawn prompt)
    L->>T2: Spawn Teammate 2 (with spawn prompt)
    L->>TL: Create task list

    T1->>TL: Claim Task A
    T2->>TL: Claim Task B

    T1->>T1: Execute Task A
    T2->>T2: Execute Task B

    T1->>T2: Share findings (direct messaging)
    T2->>T1: Challenge perspectives (direct messaging)

    T1->>TL: Mark Task A complete
    T1->>TL: Claim Task C (previously blocked by A)

    T2->>TL: Mark Task B complete
    T2->>L: Notify completion (auto-delivered)

    T1->>TL: Mark Task C complete
    T1->>L: Notify completion (auto-delivered)

    L->>L: Synthesize all results
    L->>U: Report final results
    L->>T1: Send shutdown request
    L->>T2: Send shutdown request
    L->>L: Clean up team resources

Best Use Cases

Case 1: Parallel Code Review

A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all receive thorough, simultaneous attention.

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

How it works:

• Three reviewers start from the same PR but each applies a different review lens
• The Lead synthesizes findings across all three after they finish
• Each reviewer stays focused without being distracted by others’ concerns

Case 2: Investigating with Competing Hypotheses

When the root cause is unclear, a single Agent tends to find one plausible explanation and stop looking. This prompt combats anchoring bias by making Teammates explicitly adversarial.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

Why this works:

The debate structure is the key mechanism. Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause.

Case 3: Cross-Layer Coordinated Development

When changes need to span frontend, backend, and tests simultaneously, each layer is owned by a different Teammate.

Create an agent team to implement a new user profile API:
- One teammate handles backend API endpoints (src/api/)
- One teammate handles frontend integration (src/components/)
- One teammate handles tests (tests/)

The backend teammate requires plan approval before starting.
The frontend teammate depends on the backend API definition.
The test teammate starts after both backend and frontend are complete.

How it works:

• The Lead creates a task list with dependency relationships
• The backend Teammate plans in Plan Mode first; the Lead approves before implementation begins
• Once the backend API definition is complete, the frontend Teammate is automatically notified and begins integration
• After both finish, the test Teammate’s tasks are automatically unblocked

Advanced Practical Tips

Give Teammates Enough Context

Teammates automatically load project context (CLAUDE.md, MCP servers, Skills), but they don’t inherit the Lead’s conversation history. Include task-specific details in the spawn prompt:

Good example:

Spawn a security reviewer teammate with the prompt: "Review the authentication
module at src/auth/ for security vulnerabilities. Focus on token handling,
session management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Bad example:

Spawn a teammate to look at the auth module

What’s wrong? No indication of what to look for, what the focus areas are, what technology is used, or what output format is expected.

Right-Sizing Tasks

💡 Recommendation: Having 5-6 tasks per Teammate keeps everyone productive and lets the Lead reassign work if someone gets stuck.

Avoid File Conflicts

Two Teammates editing the same file leads to overwrites. Break work so each Teammate owns a different set of files:

# Good division
Teammate 1: src/api/users.ts, src/api/auth.ts
Teammate 2: src/components/UserProfile.tsx, src/components/LoginForm.tsx
Teammate 3: tests/api/users.test.ts, tests/api/auth.test.ts

# Bad division
Teammate 1: Refactor first half of src/api/users.ts
Teammate 2: Refactor second half of src/api/users.ts  ← Conflict!

Monitor and Steer

Don’t leave the team unattended for too long. Regularly:

• Check progress: Review Teammates’ work status
• Redirect approaches: Correct course when things drift off track
• Synthesize findings: Start integrating mid-stream, don’t wait until the end
• Intervene proactively: If the Lead starts implementing instead of delegating, tell it:

Wait for your teammates to complete their tasks before proceeding

Token Usage and Cost Considerations

Agent Teams use significantly more tokens than a single session, as each Teammate has its own context window.

Principle: For research, review, and new feature development, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective.

FAQ and Troubleshooting

Teammates Not Appearing

• In in-process mode: Teammates may already be running but not visible. Press Shift+Down to cycle through
• Task not complex enough: Claude decides whether to spawn teammates based on the task; too-simple tasks won’t trigger a team
• In split panes mode: Verify tmux is installed and in your PATH

  which tmux
  

• iTerm2: Verify the it2 CLI is installed and the Python API is enabled in preferences

Too Many Permission Prompts

Teammate permission requests bubble up to the Lead, causing frequent interruptions. Solution: Pre-approve common operations in your permission settings before spawning Teammates.

Lead Shuts Down Before Work Is Done

The Lead may decide the team is finished before all tasks are actually complete. Solution:

Keep going. Wait for all teammates to finish their tasks before wrapping up.

If the Lead starts implementing instead of delegating, tell it to wait.

Orphaned tmux Sessions

If tmux sessions persist after the team ends:

# List all sessions
tmux ls

# Kill a specific session
tmux kill-session -t <session-name>

Known Limitations

Agent Teams remain experimental. Current known limitations:

💡 Good news: CLAUDE.md works normally! Teammates read CLAUDE.md files from their working directory. Use this to provide project-specific guidance to all Teammates.

Summary and Outlook

Agent Teams represents an important evolution in AI-assisted development from “single assistant” to “team collaboration.” Looking at the progression:

1. Single Agent: One Claude Code handling everything
2. Subagents: Division of labor without collaboration; hub-and-spoke model
3. Agent Teams: True team collaboration; mesh communication model

While still experimental, Agent Teams has already demonstrated powerful potential. Start with research-oriented tasks — reviewing PRs, investigating bugs, exploring technical approaches — these tasks have clear boundaries, don’t require writing code, and let you experience the power of multi-agent collaboration in a low-risk environment.

When you’re ready, gradually explore more advanced use cases like parallel development and cross-layer coordination. Remember: a good tool isn’t about how powerful it is, but whether you know when to use it — and when not to.

Related Articles

• How to Effectively Use Claude Code Subagents — Subagents fundamentals and practice
• Claude Code Subagents and Plan Mode: The New Era of Intelligent Collaboration — Advanced Subagent features and Plan Mode deep dive
• Claude Code Skills and Sandbox: Enhancing Extensibility and Security — Skills system and security sandbox
• Claude Code Hooks System and Migration Guide — Workflow automation