Reference

Agent Teams Quick Reference

Use this when you need to decide whether a task deserves an agent team, spawn teammates with clear boundaries, and steer the team without creating avoidable conflicts.

Primary source: Claude Code agent teams docs Related lesson: Work with agent teams Last checked: 2026-07-04

Use Agent Teams When

Good fit	Poor fit
Research or review across independent lenses.	One sequential task with obvious next steps.
Debugging with competing hypotheses.	Several edits to the same file or tight call chain.
Frontend, backend, and test work with clean ownership.	Routine implementation where coordination costs more than it saves.
Teammates need to challenge or message each other.	A helper only needs to return a result to the main session.

Core Model

Part	Role	Control point
Lead	The main Claude Code session that spawns and coordinates teammates.	Give it the full task, constraints, and synthesis criteria.
Teammate	A separate Claude Code instance with its own context window.	Name it and give it a bounded lens or file ownership.
Task list	Shared task state that teammates can claim and complete.	Ask the lead to split work smaller if tasks are too broad.
Mailbox	Direct inter-agent messaging.	Message a named teammate when one role needs correction.

Enable

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

Setting or command	Use when
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`	Enable the experimental feature.
`"teammateMode": "in-process"`	Keep teammates in the main terminal. This is the current default.
`"teammateMode": "auto"`	Use split panes when your environment supports them, otherwise fall back.
`"teammateMode": "tmux"`	Request tmux-backed split panes.
`"teammateMode": "iterm2"`	Request iTerm2 split panes when the `it2` CLI and Python API are available.
`claude --teammate-mode auto`	Override display mode for one session.

Prompt Skeleton

Spawn [number] teammates named [names] to [goal].

[name 1]: [lens, files, or responsibility].
[name 2]: [lens, files, or responsibility].
[name 3]: [lens, files, or responsibility].

Constraints:
- [read-only or allowed edit boundaries]
- [verification standard]
- [risk criteria]

Have teammates share findings, challenge weak assumptions,
and wait until all are done. Then synthesize [deliverable].

In-Process Controls

Control	Action
`Up` / `Down`	Select a teammate in the agent panel.
`Enter`	Open the selected teammate transcript and message it directly.
`Esc`	Interrupt the selected teammate's current turn.
`x`	Stop the selected teammate.
`Ctrl+T`	Toggle the task list while viewing a teammate.

Steering Phrases

Situation	Phrase
The lead starts implementing too early.	`Wait for your teammates to complete their tasks before proceeding.`
One teammate needs a narrower task.	`Ask verifier to focus only on offline verification commands.`
Everyone needs a new constraint.	`Tell each teammate not to edit files until I approve the plan.`
A teammate should exit.	`Ask the risk teammate to shut down.`
A task is too broad.	`Split the remaining work into smaller self-contained tasks.`

Safety Rules

Start with 3-5 teammates for most workflows; add more only when the work is genuinely independent.
Use read-only research or review for the first drill.
Include task-specific context because teammates do not inherit the lead's conversation history.
Give each implementation teammate a separate file, module, or ownership boundary.
Permission prompts bubble up to the lead. A teammate cannot approve them for you.
Subagent definitions can be reused as teammate types, but their skills and MCP server frontmatter are not applied when used this way.
In-process teammates are not restored by /resume or /rewind.
There is one team per session, no nested teams, and the main session remains the lead.

Troubleshooting

You see	Do this
Teammates do not appear.	Check the feature env var, task complexity, and the agent panel. For split panes, check tmux or iTerm2 setup.
Too many permission prompts.	Pre-approve common safe operations before spawning teammates, or use a read-only first pass.
A teammate stops after an error.	Open its output, give targeted instructions, or spawn a replacement teammate.
Tasks look blocked but work seems done.	Inspect the teammate output and tell the lead to update or nudge the task status.
After resume, old teammates are missing.	Spawn fresh teammates. In-process teammates are not restored.