Your Claude Code Sessions Can Now Coordinate: A Practical Guide to Agent Teams

TL;DR: One CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 flag turns your session into a team lead that spawns independent Claude Code teammates, each with their own context window, working from a shared task list. Still experimental — no resume support, and behavior changes without notice.

What you'll be able to do after this: run parallel implementation, review, or research across multiple Claude Code sessions without managing the coordination by hand.

Claude Code's agent team mode lets one session act as team lead: it spawns teammates (separate Claude Code instances, each with their own context window), assigns tasks from a shared list, and receives idle notifications when they finish. Teammates can message each other directly — they don't route everything through the lead.

Enabling it:

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

Then describe what you want in natural language:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage

Three rules that determine whether it works:

1. Write spawn prompts as if teammates have never seen your conversation. They haven't — teammates don't inherit the lead's history. Include the file path, the goal, and the constraints directly in the spawn prompt.

2. Size tasks so each produces one clear deliverable. A function, a test file, a review. Too small: coordination overhead exceeds the benefit. Too large: a teammate works 20 minutes in the wrong direction before you notice.

3. Give each teammate ownership of separate files. Two teammates editing the same file don't merge — they overwrite. Split work by module or file set before spawning.

When to prefer subagents instead: sequential tasks, shared file dependencies, or any job where you need the result back in the lead's context before continuing — subagents return their output directly; teammates send an idle notification without their output.

Real limits: experimental — /resume doesn't restore in-process teammates after a restart; enabling it can cause Claude to spawn teammates even when you asked for subagents; token cost scales linearly with active teammates; behavior changes without notice.

Sources: Agent teams — code.claude.com · Cross-session messaging — code.claude.com · Claude Code Cross-Session Messaging Guide — kylon.io