Agent Teams: Agents That Communicate With Each Other

Subagents vs. Agent Teams: The Key Difference

Subagents report results back to the main agent and only to the main agent. They never talk to each other. Coordination flows through the orchestrator.

Agent teams are different. Each teammate is a full, independent Claude Code session. Teammates can message each other directly. They share a task list. They can challenge each other's findings, debate hypotheses, and self-assign work — all without going through the main session.

This distinction matters for task design. Use subagents when you need focused workers that report back. Use agent teams when teammates genuinely need to collaborate, compare findings, or argue toward consensus.

Enabling Agent Teams

Agent teams are experimental and disabled by default as of July 2026. Enable them by setting an environment variable in your settings:

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

Or set it in your shell before launching Claude Code. Without this variable, Claude will not spawn or propose teammates — no team directories are written, and no coordination infrastructure exists.

Starting a Team

Once enabled, describe the task and the teammates you want in natural language. Claude handles the rest:

Spawn three teammates to investigate this performance regression:
- One focused on database query patterns
- One examining the caching layer
- One profiling the application code

Have them share findings and challenge each other's theories.

The lead (your main session) populates a shared task list, spawns teammates, and coordinates work. Each teammate starts with the same project context a regular session would receive: CLAUDE.md, MCP servers, and skills. The lead's conversation history does not carry over to teammates.

How Teammates Communicate

Teammates communicate through an automatic mailbox system. When a teammate sends a message to another teammate by name, it arrives automatically — no polling required. The lead does not need to relay messages between teammates.

The shared task list is the other coordination mechanism. Tasks have three states: pending, in progress, and completed. Tasks can depend on other tasks — a dependent task cannot be claimed until its dependencies are completed. File locking prevents race conditions when multiple teammates try to claim the same task simultaneously.

Teammates discover each other through a team config file at ~/.claude/teams/{team-name}/config.json, which contains each teammate's name, agent ID, and agent type.

The TeammateIdle Hook

The TeammateIdle hook event fires when a teammate is about to go idle after completing its current turn. This is where you enforce quality gates — if the hook exits with code 2, it sends feedback to the teammate and keeps it working rather than letting it stop.

{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/scripts/validate-teammate-output.py",
            "statusMessage": "Validating teammate output..."
          }
        ]
      }
    ]
  }
}

If the validation script finds the output incomplete and exits with code 2, Claude reads stderr and sends that feedback to the teammate to continue working. This is how you automate quality assurance across a team without manually reviewing each teammate's output after every turn.

Known Limitations

Because agent teams are experimental, several limitations apply as of July 2026:

• No session resumption with in-process teammates. /resume and /rewind do not restore in-process teammates after a session ends.
• Task status can lag. Teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. Check and update manually if tasks appear stuck.
• No nested teams. Teammates cannot spawn their own teammates. Only the lead manages the team.
• No background subagents from in-process teammates. A teammate's own subagents must run in the foreground.
• Lead is fixed. The main session is the lead for its lifetime.

Despite these limitations, agent teams are particularly effective for research and review tasks where multiple independent perspectives genuinely improve the outcome.