Orchestrate Coordinated by a lead agent experimental · off by default · v2.1.32+ ⓘ legend

Agent teams

Multiple full Claude sessions working together: one lead coordinates and synthesizes; teammates work in their own context windows and message each other via a shared task list. The step up from subagents when workers must talk.

Analogy — a small project squad with a tech lead. Unlike interns running solo errands (subagents), these peers share a kanban board, pick up tasks, and DM each other when one’s work depends on another’s.

Mechanism

The lead (fixed for the team’s life) creates tasks, assigns them, and synthesizes; teammates can also self-claim the next unblocked task, and you can message any teammate directly. Coordination lives in a shared task list (~/.claude/tasks/{team}/) and a mailbox. Each teammate has a fully independent context window.

# enable (settings.json env or shell)
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# then, in natural language:
"Create an agent team to review this PR from three angles."

Scale, display modes & limits

Recommended 3–5 teammates, ~5–6 tasks each. No nested teams; one team per lead. Token cost scales linearly (each teammate is a separate Claude instance).

Display via teammateMode: in-process (any terminal), tmux/split-panes (needs tmux or iTerm2; not VS Code terminal / Windows Terminal / Ghostty), auto.

Resumability is weak: /resume and /rewind don’t restore in-process teammates — after resume, tell the lead to spawn new ones.

When to reach for it

✓

Parallel work with real value: multi-lens PR review, independent modules, competing debugging hypotheses, cross-layer changes (frontend/backend/tests).

✓

Subagents hit context limits, or need to communicate — the documented transition point.

✓

Start with non-code research/review tasks to get a feel for it.

When not to

Sequential tasks, same-file edits, or many dependencies → one session or subagents (cheaper).

Workers don’t need to talk → subagents.

Dozens-to-hundreds of well-scoped tasks → a dynamic workflow.

Best practices

★

Give each teammate enough context in the spawn prompt — they load CLAUDE.md/MCP/skills but not the lead’s conversation history.

★

Partition files so no two teammates edit the same one (teams do not auto-isolate with worktrees).

★

Tell the lead to wait for teammates rather than doing the work itself.

★

Use TeammateIdle/TaskCompleted hooks as quality gates; always clean up via the lead.

Sources

Agent teams · Agent team token costs