Claude Code Agent Teams in Practice: Team Lead, Point-to-Point Messaging, and a Shared Task Board

🌏 中文版

This is the Agent Teams installment of the "Claude Code Deep Dives" series. F1, the multi-agent overview, mapped the whole territory, and D4 on sub-agents covered the lightweight way to parallelize; this post handles the heavyweight option — multiple Claude Code instances forming a long-lived team. The feature is experimental and disabled by default, and the official docs are upfront about its known limitations, so half of this post is about how to use it and the other half is about when not to.

How It Differs from Sub-agents

A sub-agent is "dispatch, then collect the report": the main conversation opens a fresh context window, the sub-agent does its work, summarizes results back, and its lifecycle ends there. Teammates in an agent team are different — they are long-lived, full Claude Code sessions — each with its own context window, loading the same CLAUDE.md, MCP servers, and skills at spawn time, but not inheriting the lead's conversation history.

The official comparison (see also the official sub-agents docs for the full mechanics):

Condensed into three sentences: Agent Teams packages long-lived teammates, a shared task board, and your ability to jump into any teammate's session as one collaboration mode. Messaging itself is no longer unique to Agent Teams; the difference is that messaging works alongside the task board and lead coordination.

Starting Your First Team

Agent teams are controlled by CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, disabled by default. Add this to settings.json:

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

As of v2.1.178 you no longer ask Claude to create and name a team first — just describe the task and the teammates 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

Claude populates a shared task list, spawns a teammate per perspective, and synthesizes findings once everyone finishes.

One side effect worth knowing: with this variable enabled, subagents that Claude names on its own also launch as teammates, even if you never asked for a team. If part of your flow really only needs the dispatch-and-report behavior of a subagent, set the variable back to "0" — no session restart required. Also note that non-interactive mode (-p flag, Agent SDK sessions) never spawns teammates.

What the Lead and Teammates Each Do

Architecturally there are exactly four components:

Everything lives locally: team config at ~/.claude/teams/{team-name}/config.json, tasks at ~/.claude/tasks/{team-name}/. The team name derives from the session ID (session- plus the first eight characters); the config directory is removed automatically when the session ends, while the task list persists so a resumed session picks up where it left off.

The core rule of the division of labor: you instruct the lead, and the lead instructs the teammates. For complex or risky tasks you can add a plan approval gate — require a teammate to stay in read-only plan mode until the lead session approves its plan. Do not mistake this for human review: the official docs state that the lead session grants the approval as soon as the request arrives, without reviewing it. The real guardrail remains the later permission prompts for edits and commands.

On permissions: teammates inherit the lead's permission settings. You can change individual modes after spawn but not at spawn time, and teammate permission prompts bubble up to the lead session for you to handle.

The Messaging Model: Point-to-Point, No Broadcast

Teammates communicate through SendMessage, and it is strictly addressed: reaching everyone means sending one message per recipient. The official wording is "To reach everyone, send one message per recipient" — there is no broadcast operation.

Messages are delivered automatically; the lead never polls. When a teammate finishes and stops, it sends an idle notification to the lead — but the notification does not carry the teammate's output. Results get shared by messaging the lead or updating the shared task list.

Under the hood, each agent has a mailbox JSON file (~/.claude/teams/{team-name}/inboxes/{agent-name}.json), and a message counts as sent only when the write succeeds. One security rule is worth remembering: recipients are told the message came from another Claude session, not from you, so a teammate cannot approve permission prompts on your behalf, and an action you denied cannot be relayed to another teammate to bypass the check.

At the tool layer: SendMessage handles inter-agent messaging (and since v2.1.224 can also reach your other Claude Code sessions), while ListAgents lists every agent Claude can message — it requires v2.1.224 or later and appears only in sessions where cross-session messaging is enabled.

Managing the Task Board

The shared task list runs on four tools: TaskCreate, TaskGet, TaskList, and TaskUpdate. Tasks have three states: pending → in progress → completed. Dependencies are managed automatically — a pending task with unresolved dependencies cannot be claimed, and when a teammate completes a task, downstream tasks unblock without any action from you.

Assignment goes two ways:

• Lead assigns: tell the lead which task goes to which teammate.
• Self-claim: after finishing its current work, a teammate picks up the next unassigned, unblocked task on its own.

Claiming uses file locking to prevent two teammates grabbing the same task simultaneously. To enforce quality gates, use hooks: TeammateIdle (when a teammate is about to go idle), TaskCreated, and TaskCompleted — exit code 2 blocks the action and feeds back a message.

For day-to-day operation: Ctrl+T toggles the task list display; in the agent panel, use the up and down arrow keys to select a teammate, then press Enter to open its transcript and message it directly; press x on a selected teammate to stop it. Esc clears the selection; while you are viewing a teammate's transcript, Esc interrupts that teammate's current turn.

teammateMode: Two Display Modes

• In-process (default): all teammates run inside your main terminal, switched via the agent panel. Works in any terminal with zero extra setup.
• Split panes: each teammate gets its own pane — everyone's output visible at once, click into any pane to interact. Requires tmux or iTerm2.

Configure via teammateMode in ~/.claude/settings.json: "in-process", "auto" (split panes when already inside tmux or when iTerm2 has the it2 CLI installed, otherwise fall back to in-process), "tmux" (enable split-pane mode and auto-detect tmux versus iTerm2 based on the terminal), or "iterm2" (v2.1.186+, explicitly iTerm2 native split panes, requires the it2 CLI). Note the default change: as of v2.1.179 the default moved from "auto" to "in-process", so if you were used to split panes, set it back yourself. For a single session, override with claude --teammate-mode auto (an experimental flag that does not appear in --help).

While viewing an in-process teammate, your plain text and skills go to that teammate, but built-in commands still execute in the lead's session. A teammate's model and fast mode are fixed at spawn time, so /model and /fast only change the lead's settings; /effort still applies to later turns for the teammate you are viewing.

Use Cases and the Cost Warning

The four strongest use cases named by the official docs: research and review (multiple angles investigating and challenging each other's findings), new modules or features (each teammate owns separate files without stepping on others), debugging with competing hypotheses (five teammates try to disprove each other's theories — the surviving theory is most likely the root cause), and cross-layer coordination (one teammate each for frontend, backend, and tests). If you're new, start with tasks that don't write code to validate the value first.

The negative list is just as clear: sequential tasks, same-file edits, and work with many dependencies are better served by a single session or subagents.

Cost is the most practical brake: each teammate carries its own context window, so token usage scales linearly with headcount — the official docs state plainly that it costs significantly more than a single session. The official guidance is to start most workflows with 3 to 5 teammates; if you have 15 independent tasks, 3 teammates is usually a reasonable starting point, and three focused teammates often outperform five scattered ones. Factor the known limitations into any decision too: in-process teammates aren't restored by /resume or /rewind, task status updates can lag, shutdown can be slow, a session supports exactly one team, teammates cannot spawn their own teammates, the lead role is fixed and cannot be transferred, and split-pane mode is not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

Lessons Learned

A sub-agent is a function call; an agent team is a coworker. The difference isn't whether you can parallelize (both can) — it's the coordination style and lifecycle: teammates coexist over time, can be entered directly by you, and self-coordinate on a shared task board. The price is linearly rising token cost plus the rough edges of an experimental feature. My recommendation: run one team through a boundary-clear review or research task first, confirm the coordination gains actually exceed the cost, and only then hand it code-writing work.

References

• Orchestrate teams of Claude Code sessions — Claude Code Docs — Official Agent Teams documentation: enablement, display modes, task board, mailbox architecture, hooks, limitations, and troubleshooting
• Tools reference — Claude Code Docs — Current status, version requirements, and permission columns for SendMessage, ListAgents, and the TaskCreate family
• Create custom subagents — Claude Code Docs — Sub-agent lifecycle, tool filtering, and its "runs within a single session" positioning; the baseline for the Agent Teams comparison table
• Message your other Claude Code sessions — Claude Code Docs — Cross-session messaging, ListAgents visibility, message safety boundaries, and version requirements
• Manage costs effectively — Claude Code Docs — Official guidance on Agent Teams token costs, team size, and cost controls

Changelog

• 2026-03-28: Outline skeleton created.
• 2026-08-26: Expanded into full prose based on the official docs (code.claude.com, including v2.1.178+ behavior); corrected teammate switching to arrow-key selection + Enter, removed the nonexistent broadcast description, and added teammateMode "iterm2" plus the current status of SendMessage/ListAgents.
• 2026-08-29: Aligned with the current official Agent Teams docs: corrected plan approval behavior, added x to stop a teammate, and updated the subagent messaging and teammateMode descriptions.