Agent teams

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

	Sub-Agents (Task)	Agent Teams	Manual sessions
Context	Clean, result returned	Clean, independent	Clean, independent
Communication	Return to parent only	Direct messaging between agents	None (manual)
Coordination	Main agent handles everything	Shared task list	Manual
Token cost	Low	High (1 context per agent)	High
Ideal for	Focused tasks	Complex collaborative work	Independent branches

Architecture

Component	Role
Team Lead	Main session, creates the team, coordinates the work
Teammates	Independent Claude Code instances, execute the tasks
Task List	Shared list of tasks with statuses and dependencies
Mailbox	Messaging system for inter-agent communication

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:

Pattern	Teammates	Use case
Audit	3-4 agents (security, perf, a11y, design)	Full quality audit
Feature	2-3 agents (frontend, backend, tests)	Multi-layer development
Debug	3-5 agents (concurrent hypotheses)	Complex bug investigation
Review	3 agents (security, perf, coverage)	Parallel code review

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."
3. Each agent works independently
4. The lead synthesizes into a consolidated report
5. 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."
2. Manage dependencies via the task list (backend before frontend)
3. The test-writer can start with the tests (TDD) while the devs are planning
4. 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 runs on 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 (default opus alias since 2026-07-24, within ~0.5% of Fable 5's peak at half the price) is the right lead model; --model claude-fable-5 remains a deliberate niche escalation (~2× Opus 5) for the rare run where Fable's last half-percent matters. Per-session selection only: agent model: frontmatter is unchanged and there is no fable tier alias. Fable 5 has been generally available since 2026-07-01.

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