Agent Teams (Multi-Agent Orchestration)

Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management.

Prerequisites

• Claude Code >= 2.1.19
• Feature flag enabled: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
• tmux (optional): for split-panes mode

Activation

Add to .claude/settings.local.json or .claude/settings.json:

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

Or via environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

When to use Agent Teams vs Sub-Agents

┌────────────────────────────────────────────────────────────────────┐
│           AGENT TEAMS vs SUB-AGENTS: DECISION GUIDE                │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  AGENT TEAMS if:                                                   │
│  - Agents need to COMMUNICATE with each other                     │
│  - COMPLEX work requiring discussion and collaboration            │
│  - Tasks with coordination (cross-review, debate, consensus)      │
│  - 3+ agents working in parallel over a long duration             │
│                                                                    │
│  SUB-AGENTS (Task tool) if:                                        │
│  - FOCUSED task where only the result matters                     │
│  - No need for inter-agent communication                          │
│  - 1-2 agents for short tasks                                     │
│  - Token economy is the priority                                  │
│                                                                    │
│  MANUAL PARALLEL SESSIONS (git worktrees) if:                      │
│  - Full control over each session                                 │
│  - No need for automatic coordination                             │
│  - Work on completely independent branches                        │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Comparison table

Architecture

Mechanics: native docs own them

Display modes, keyboard shortcuts, the team lifecycle, and the current limitations are native UI surface — they change with the CLI and re-documenting them here has already drifted once (full re-sync needed at 2.1.198). See the official Agent Teams documentation for the current mechanics; this skill keeps only what the foundation adds: the decision guide, cost discipline, and the patterns below.

Launch example

Create a team of 3 agents to audit this project in parallel:
- A security agent (focus on OWASP Top 10)
- A performance agent (focus on Core Web Vitals)
- An accessibility agent (focus on WCAG 2.1 AA)
Each produces a report, then synthesize the results.

Delegate mode (recommended for teams > 3 agents)

Delegate mode prevents the lead from implementing itself, forcing it to stay in coordination:

• Activate with Shift+Tab after creating the team
• The lead can only: spawn, send messages, manage tasks, shutdown
• Recommended when you want the lead to focus on orchestration

Best practices

• 2-5 teammates: beyond that, coordination becomes expensive in tokens
• 5-6 tasks per agent: enough to keep agents productive
• File isolation: each agent works on different files
• Explicit context: give a detailed prompt to each teammate at spawn
• Plan approval: for risky tasks, ask the lead to approve the plan before execution
• Regular monitoring: check progress, redirect if needed

Pre-configured patterns

See @patterns.md for the 4 ready-to-use patterns:

Full example: Parallel audit

/work:work-team "Full project audit"

The lead will:

1. Create an "audit-team"
2. Spawn 3 teammates:

• security-reviewer: "Audit the code for OWASP Top 10 vulnerabilities. Focus on authentication, injections, and sensitive data."
• perf-analyst: "Analyze performance. Focus on slow queries, bundle size, and Core Web Vitals."
• a11y-checker: "Check WCAG 2.1 AA accessibility. Focus on contrast, keyboard navigation, and screen readers."

1. Each agent works independently
2. The lead synthesizes into a consolidated report
3. Shutdown and cleanup

Full example: Feature as a team

/work:work-team "Implement the notifications system"

The lead will:

1. Create the team and decompose the work:

• backend-dev: "Implement the notifications service in src/services/notification.ts and the API endpoints."
• frontend-dev: "Create the NotificationCenter component in src/components/ and the associated hooks."
• test-writer: "Write the unit and integration tests for the notifications system."

1. Manage dependencies via the task list (backend before frontend)
2. The test-writer can start with the tests (TDD) while the devs are planning
3. Merge once all agents are done

Recent CLI surface (CLI 2.1.142+)

The claude agents subcommand for dispatched background sessions gained per-session configuration flags: --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort, --dangerously-skip-permissions. Useful when a teammate needs a different model than the lead (e.g. dispatch a Haiku worker for grep-heavy tasks while the lead stays on Opus), a tighter permission mode, or an alternate .mcp-config. Fast mode (a research preview) runs on Opus 5.5, Opus 5 and Opus 4.8 (Opus 4.7 was removed from fast mode in CC 2.1.219).

For the foundation's own heaviest dispatched sessions, Opus 5.5 (default opus alias since 2026-09-22) is the right lead model; --model claude-fable-5-1 remains a deliberate niche escalation for the rare run where the top tier's last half-percent matters. claude-fable-5-1 has been the default Fable model since 2026-09-01. A fable alias now exists in sub-agent model: frontmatter, but this foundation pins no agent to it — a cost decision, not a limitation of the tool.

Background agents (CLI 2.1.198+, July 2026)

Anthropic hardened dispatched background sessions:

• Draft-PR handoff. A background agent launched from claude agents that finishes code work in a worktree now commits, pushes, and opens a draft PR on its own instead of stopping to ask. Plan for a review-the-draft step rather than a blocking hand-back.
• Notification hooks. Sessions that need input or complete fire the Notification hook with agent_needs_input / agent_completed — wire these to drive the lead (or the human) instead of polling the roster.
• `/agents` wizard removed. Create or manage sub-agents by editing .claude/agents/ directly (the foundation's own agents live there) or by asking Claude — there is no interactive wizard anymore.

Agent View

Anthropic ships an Agent View: a unified terminal dashboard that lists every running session, their current state, last responses, and a key to jump back into any of them. Complementary to the in-process Team Lead model — Agent View covers cross-process sessions that the Team Lead can't see. From CLI 2.1.196 it opens with a single ← press and reflects the notification/draft-PR states above. See the official note for activation.

See also

• Skill parallel-agents for orchestration via Task sub-agents
• Skill git-worktrees for manual parallel sessions
• Skill session-handoff for context handoff between sessions
• /work:work-team for the direct launch command