54 lines
3.4 KiB
Markdown
54 lines
3.4 KiB
Markdown
 
|
# Claude Code: Orchestrate teams of Claude Code sessions (agent teams)
|
||
|
|
|
||
|
|
## Metadata
|
||
|
|
|
||
|
|
| Field | Value |
|
||
|
|
|---|---|
|
||
|
|
| Institute | Molodetz Institute — Research & Retrieval Division |
|
||
|
|
| Subject | background-work-limits |
|
||
|
|
| Document type | Source Dossier |
|
||
|
|
| Tier | 1 |
|
||
|
|
| Source title | Claude Code: Orchestrate teams of Claude Code sessions (agent teams) |
|
||
|
|
| Source URL | https://code.claude.com/docs/en/agent-teams |
|
||
|
|
| Source publisher / author | Anthropic |
|
||
|
|
| Source type | vendor docs |
|
||
|
|
| Source date (published) | Unknown — not stated |
|
||
|
|
| Date researched | 2026-10-25 |
|
||
|
|
| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
|
||
|
|
| Research method | direct page fetch |
|
||
|
|
| Confidence | High |
|
||
|
|
| Status | Active |
|
||
|
|
|
||
|
|
## Summary
|
||
|
|
|
||
|
|
The documentation of Claude Code's experimental agent teams: a lead session, teammates in their own context windows, in-process or split-pane display, a shared task list and mailboxes. It is the closest shipped precedent for showing parallel agents in separate panes.
|
||
|
|
|
||
|
|
## Key findings
|
||
|
|
|
||
|
|
- Two display modes: in-process (agent panel below the prompt; arrows select, Enter opens a transcript, x stops a teammate) and split panes (each teammate its own pane; click into a pane to talk to it). Split panes need tmux or iTerm2; the default mode is in-process and `auto` uses split panes only inside tmux.
|
||
|
|
- Split panes are not supported in VS Code's terminal, Windows Terminal or Ghostty; orphaned tmux sessions after a session ends are a documented problem (`tmux kill-session`).
|
||
|
|
- In the panel, idle rows hide 30 seconds after everything is idle, and more than three idle teammates collapse into one `N idle agents` row; working and failed teammates always keep their rows.
|
||
|
|
- Start with 3-5 teammates; token cost scales linearly with the number of teammates; 5-6 tasks per teammate keeps everyone busy; avoid two teammates editing the same file.
|
||
|
|
- Teammates do not inherit the lead's conversation; a teammate that finishes sends an idle notification carrying its final answer to the lead, and one that fails on an API error notifies the lead with the error text.
|
||
|
|
- Shutdown is cooperative: the lead sends a shutdown request, the teammate can approve or reject; shutdown can be slow because a teammate finishes its current call first.
|
||
|
|
- Teammates cannot spawn teammates (no nested teams); a teammate's permission prompts bubble up to the lead; a message from another agent is never treated as user consent.
|
||
|
|
- Model precedence for a teammate: the spawn prompt, then the subagent definition, then `CLAUDE_CODE_SUBAGENT_MODEL`, then the lead's model; before v2.1.251 the environment variable came first.
|
||
|
|
|
||
|
|
## Pros / strengths
|
||
|
|
|
||
|
|
Primary documentation with concrete display, cost and shutdown behavior, including the honest list of limitations.
|
||
|
|
|
||
|
|
## Cons / limitations / caveats
|
||
|
|
|
||
|
|
Experimental feature; the panel and mailbox mechanics are specific to Claude Code; split panes rely on an external multiplexer, which tai now has built in.
|
||
|
|
|
||
|
|
## Relevance to tai
|
||
|
|
|
||
|
|
Direct precedent for the layout and lifecycle: one pane per agent, working rows stay visible, idle rows fade, a cap on useful team size, nested teams forbidden, cooperative shutdown. tai takes the cap (8, panels limited by space), the fade (linger then close) and the no-nesting rule (workers are depth-limited), and does it on its own multiplexer so it needs neither tmux nor iTerm2.
|
||
|
|
|
||
|
|
## Changelog
|
||
|
|
|
||
|
|
| Date | Change |
|
||
|
|
|---|---|
|
||
|
|
| 2026-10-25 | Initial dossier created. |
|