> ## Documentation Index > Fetch the complete documentation index at: https://vietbui.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Agent Teams > Agent teams coordinate multiple Claude Code instances working in parallel. One session acts as team lead (coordinator); others are teammates (workers), each… # Agent Teams Agent teams coordinate multiple Claude Code instances working in parallel. One session acts as **team lead** (coordinator); others are **teammates** (workers), each with its own context window. Teammates can communicate directly with each other — unlike subagents, which only report back to the parent. **Enable:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json env block. ## Architecture | Component | Role | | ------------- | -------------------------------------------------------------------------- | | **Team lead** | Main Claude Code session; creates team, spawns teammates, coordinates work | | **Teammates** | Separate Claude Code instances; each owns assigned tasks | | **Task list** | Shared work items; teammates claim and complete; dependency-aware | | **Mailbox** | Direct messaging between any agents | State stored locally: * Team config: `~/.claude/teams/{team-name}/config.json` * Task list: `~/.claude/tasks/{team-name}/` ## When to Use Teams (vs Subagents) Use **subagents** when: workers only need to report results back; no inter-agent coordination required; lower token budget. Use **agent teams** when: * Teammates need to challenge each other's findings (competing hypotheses debugging) * Parallel research across independent domains * Cross-layer changes (frontend / backend / tests each owned by a different teammate) * New module development with non-overlapping file ownership **Anti-patterns**: sequential tasks, same-file edits, work with many dependencies — use single session instead. DeepMind found unstructured multi-agent networks amplify errors up to 17.2x. Benefits plateau at \~4 concurrent agents. ## Starting a Team ```text theme={null} Create an agent team to review PR #142. Spawn three reviewers: - One focused on security implications - One checking performance impact - One validating test coverage ``` Best practice: 3–5 teammates, 5–6 tasks per teammate. Scale up only when work genuinely benefits from parallelism. ## Task Management Tasks have states: `pending | in-progress | completed`. Tasks can depend on other tasks (blocked until dependency completes). Claiming uses file locking to prevent race conditions. Lead assigns or teammates self-claim after finishing current task. ## Quality Gate Hooks ```json theme={null} { "hooks": { "TeammateIdle": [{ "hooks": [{ "type": "command", "command": "./scripts/validate-output.sh" }] }], "TaskCompleted": [{ "hooks": [{ "type": "command", "command": "./scripts/check-tests.sh" }] }], "TaskCreated": [{ "hooks": [{ "type": "command", "command": "./scripts/validate-scope.sh" }] }] } } ``` `TeammateIdle`: exit 2 to send feedback and keep teammate working. `TaskCompleted`: exit 2 to block completion and request more work. `TaskCreated`: exit 2 to reject task creation. ## Using Subagent Definitions as Teammates Define roles once in `~/.claude/agents/` or `.claude/agents/`, reuse in both subagent and teammate contexts: ```text theme={null} Spawn a teammate using the security-reviewer agent type to audit the auth module. ``` Teammate honors the definition's `tools` allowlist and `model`. Definition body appended to teammate system prompt. `skills` and `mcpServers` frontmatter NOT applied in teammate mode. ## Parallel Code Review Pattern (wshobson-derived) ```text theme={null} Create a team with 3 reviewers: - security-auditor: OWASP top 10, auth, secrets - performance-reviewer: N+1, bottlenecks, bundle size - test-coverage-reviewer: missing cases, edge cases, assertions ``` Each applies a distinct lens. Lead synthesizes after all complete. ## Competing Hypotheses Debugging ```text theme={null} Spawn 5 teammates to investigate bug hypotheses. Have them debate and try to disprove each other's theories. Update findings.md with consensus. ``` The debate structure prevents anchoring — sequential investigation is biased toward the first plausible explanation found. Multiple independent investigators converge on actual root cause. ## Best Practices * **Give teammates context in spawn prompt** — they don't inherit lead's conversation history. Include: file paths, constraints, what "done" means. * **Avoid file conflicts** — each teammate should own a distinct set of files. * **3–5 teammates** — beyond \~5, coordination overhead and token cost outweigh benefits. * **Monitor and steer** — don't let teams run unattended too long; redirect approaches that aren't working. * **Clean up properly** — `Clean up the team` tells the lead to remove shared resources. Always use the lead, not a teammate, to run cleanup. ## Display Modes * **In-process** (default): teammates run in main terminal. Shift+Down cycles through them. * **Split panes**: requires tmux or iTerm2. Each teammate in its own pane. Set `"teammateMode": "tmux"` in settings.json. ## Known Limitations (experimental) * No session resumption with in-process teammates * Task status can lag (may need manual nudge) * One team per session (lead is fixed for team lifetime) * No nested teams (teammates can't spawn their own teams) * Split panes not supported in VS Code terminal, Windows Terminal, Ghostty ## Agent View — Background Sessions UI `claude agents` — full-screen TUI (CC v2.1.139+, research preview) listing all background sessions grouped by state. Distinct from agent teams: shows individual background sessions, not coordinated teammates. **Session states**: Working (animated), Needs input (yellow), Idle (dimmed), Completed (green), Failed (red), Stopped (grey). **Key operations:** * `Space` (Peek): shows what session needs/produced; type reply and press Enter without attaching * `Enter`/`→` (Attach): full interactive session; `←` on empty prompt to detach * `/bg` or `/background` from inside session; `claude --bg ""` from shell * `claude attach `, `claude logs `, `claude stop `, `claude respawn ` **File isolation**: every background session gets an isolated git worktree under `.claude/worktrees/` before editing. Worktree removed on session delete — push/commit first. **Supervisor process**: background sessions hosted by a per-user supervisor. Starts automatically; sessions survive terminal close. Sessions stop on machine sleep — resume with `claude respawn --all`. State at `~/.claude/daemon.log`, `~/.claude/daemon/roster.json`, `~/.claude/jobs//state.json`. **PR status dots**: yellow (checks failing/pending), green (checks passed), purple (merged), grey (draft/closed). **Row summaries**: generated by a Haiku-class model; describes what the session is doing without opening the transcript. Refreshes at most every 15 seconds while active. ## Related Pages * [Agent Subagents](/concepts/agent-subagents) — subagents and when to prefer them over teams * [Agent Harness](/concepts/agent-harness) — harness components; teams as the highest coordination layer * [Context Degradation Patterns](/concepts/context-degradation) — why each teammate needs its own context window * [Worktree Isolation](/concepts/worktree-isolation) — worktrees as the alternative for long-running parallel tasks (>30 min) * [Shared Task Queue (Cross-Worktree)](/concepts/shared-task-queue) — filesystem inbox for cross-worktree coordination; pull model alternative to in-process task list