Claude Code Teams: Multi-Agent Orchestration Guide

When Faros AI tracked 22,000 developers across 4,000 teams through two years of increasing AI tool adoption, they found PR merge rates rose 16.2% while the incidents-to-PR ratio climbed 242.7%. More code shipped faster and broke more things. The problem is not speed. The problem is that a single AI session handling research, implementation, testing, and review in one context window has no structural check on quality. As the context fills with file reads and test output, earlier instructions degrade and quality suffers.

Claude Code agent teams address this by splitting work across multiple independent AI sessions. One session acts as team lead. Others work as specialized teammates, each with its own fresh context window, focused on a single slice of the problem. They share a task list, message each other directly, and coordinate without funneling everything through one overloaded context.

This is a different feature from the "Teams" billing plan for Claude subscriptions. That plan ($100/seat/month, 5-seat minimum) manages seats and billing for human users. Agent teams are an orchestration feature inside Claude Code that coordinates multiple AI instances on one codebase. Most guides conflate the two, which makes searching for setup instructions frustrating.

This guide covers how to enable agent teams, spawn and control teammates, choose display modes, design tasks for parallel work, enforce quality gates, and persist output for human review.

Three things in the Claude ecosystem share the word "team," and they solve different problems.

Claude Teams Plan is a subscription tier for organizations. It includes SSO, admin controls, central billing, and higher usage limits. It has nothing to do with multi-agent orchestration. You can run agent teams on any Claude plan that supports Claude Code, including Pro and Max.

Claude Code Subagents are lightweight workers that run inside a single session. The parent session spawns a subagent, it does focused work like searching code or running tests, and returns a summary. Subagents cannot talk to each other. They report only to the parent. Think of them as temporary assistants who run an errand and come back with the result.

Claude Code Agent Teams are full independent Claude Code sessions coordinated through a shared task list and mailbox. Each teammate has its own context window, reads CLAUDE.md and project configuration independently, and can message any other teammate by name. The lead session manages coordination, but teammates can self-organize by claiming unblocked tasks and challenging each other's findings.

The key architectural differences:

• Context isolation: both subagents and teammates get their own context windows. But subagent results are summarized back into the parent context, while teammates remain fully independent.

• Communication: subagents report back to the parent only. Teammates message each other directly without routing through the lead.

• Coordination: the parent manages all subagent work. Agent teams use a shared task list where teammates self-claim available tasks.

• Cost: subagents are cheaper because only summaries return to the parent context. Agent teams use more tokens because each teammate runs as a separate Claude instance.

Choose subagents when the work is sequential or each piece is self-contained. Choose agent teams when teammates need to share findings, review each other's work, or coordinate across multiple layers of a codebase.

Agent teams are experimental and disabled by default. Enable them by setting one environment variable, either in your shell or through settings.json.

Add this to your Claude Code settings.json:

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

Or export it in your shell before launching Claude Code:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Once enabled, describe the work and the teammates you want in natural language. Claude handles spawning and coordination based on your prompt.

A code review prompt that works well:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Claude populates a shared task list, spawns one teammate per role, and synthesizes findings when all three finish. This works because the three roles are independent and can explore the problem without waiting on each other.

A feature build prompt:

I'm building a REST API for user notifications. Spawn teammates:
- One for the database schema and migrations
- One for the API endpoints and validation
- One for the test suite

Each teammate works on its own set of files. The lead tracks progress and resolves integration questions across the three.

You can also specify which model each teammate should use:

Spawn 4 teammates to refactor these modules. Use Sonnet for each.

By default, teammates do not inherit the lead's /model selection. To change this, open /config and set Default teammate model to Default (leader's model). Teammates do inherit the lead's effort level, so if you set /effort high on the lead, all teammates work at the same depth.

Store and share multi-agent output in one workspace

A shared workspace with an MCP-ready endpoint for your agent teams. Starts with a 14-day free trial.

Start 14-Day Trial

In-Process Mode

The default display mode runs all teammates inside your main terminal. The agent panel below the prompt input lists active teammates. Use arrow keys to select one, press Enter to view its transcript and type messages to it, and press Escape to interrupt its current turn. Press x on a selected teammate to stop it.

Idle teammates hide after 30 seconds and reappear on their next turn. They are still running and addressable. Send a message by name to bring one back.

Split-Pane Mode

Each teammate gets its own terminal pane. You see all output at once and click into any pane to interact directly. Split-pane mode requires tmux or iTerm2 with the it2 CLI.

Set the display mode in settings.json:

{
  "teammateMode": "auto"
}

Or pass it as a flag for a single session:

claude --teammate-mode auto

The available values are in-process (default), auto (uses split panes when tmux or iTerm2 is detected, falling back to in-process), tmux, and iterm2.

Shared Task List

The task list is the coordination backbone. Tasks have three states: pending, in-progress, and completed. Tasks can depend on other tasks. A pending task with unresolved dependencies stays blocked until those dependencies finish.

The lead creates tasks, and teammates either get assigned explicitly or self-claim the next unassigned, unblocked task after finishing their current work. Task claiming uses file locking so two teammates cannot grab the same task simultaneously.

Press Ctrl+T to toggle the task list view in your terminal.

Direct Messaging

Every teammate gets a name assigned by the lead at spawn time. Any teammate can message any other by that name, and messages arrive automatically without polling.

This is the key architectural difference from subagents. In a subagent model, Worker A cannot tell Worker B about a finding it discovered. With agent teams, Worker A sends a direct message to Worker B, and Worker B can challenge the finding or build on it. For debugging with competing hypotheses, this structure is particularly effective: teammates can actively try to disprove each other's theories, similar to a scientific debate. The theory that survives multiple independent challengers is far more likely to be the actual root cause.

Choosing Team Size

The official documentation states there is no hard cap on teammates, but practical constraints apply. Token costs scale linearly with team size because each teammate maintains its own context window. Agent teams use approximately 7x more tokens than a standard session when teammates run in plan mode.

Start with 3 to 5 teammates. This balances parallel work with manageable coordination overhead. Three focused teammates often outperform five scattered ones because each has clearer ownership and less cross-talk.

Aim for 5 to 6 tasks per teammate. If you have 15 independent work items, 3 teammates is a reasonable starting point. Having too many teammates with too few tasks wastes tokens on coordination that delivers no additional parallelism.

Designing Good Tasks

Each task should be a self-contained unit that produces a clear deliverable: a function, a test file, a review summary.

• Too small: the coordination cost exceeds the parallelism benefit. "Rename this variable" is not worth a teammate.

• Too large: teammates work too long without check-ins, increasing the risk of wasted effort if the approach is wrong.

• Right-sized: each task touches a distinct set of files and produces a testable result.

The most important constraint: break the work so each teammate owns different files. Two teammates editing the same file leads to overwrites. For changes that span frontend, backend, and tests, assign each layer to a different teammate.

Quality Gates with Hooks

Claude Code hooks let you enforce rules when teammates finish work:

• TeammateIdle: runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.

• TaskCreated: runs when a task is being created. Exit with code 2 to prevent creation with feedback.

• TaskCompleted: runs when a task is being marked complete. Exit with code 2 to block completion and send feedback.

For complex or risky changes, require teammates to plan before implementing:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

The teammate works in read-only plan mode until the lead approves the approach. If rejected, the teammate revises and resubmits. The lead makes approval decisions autonomously, but you can influence its judgment with criteria like "only approve plans that include test coverage" or "reject plans that modify the database schema."

Reusable Teammate Roles

Define roles once and reuse them across sessions. Store subagent definition files in .claude/agents/ (project scope) or ~/.claude/agents/ (user scope):

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a security code reviewer. Focus on:
1. Authentication and authorization flaws
2. Input validation gaps
3. Token and session handling

Reference the role by name when spawning:

Spawn a teammate using the security-reviewer agent type
to audit the auth module.

The teammate picks up that definition's tool restrictions and model. Team coordination tools like SendMessage and task management are always available, even when other tools are restricted by the definition.

Agent teams generate output across multiple independent sessions. The shared task list persists locally under ~/.claude/tasks/{team-name}/, but the files teammates create or review need a durable home accessible to both agents and human reviewers.

Local git repositories handle code changes well. But for build artifacts, review reports, generated documentation, and handoff packages, teams need shared persistent storage that outlives the session.

Options range from simple to intelligent. S3 buckets and Google Drive work for basic file storage. Fast.io adds an intelligence layer on top: every uploaded file is automatically indexed for semantic search and AI-powered Q&A, with no separate vector database or indexing step required.

Every org starts with a 14-day free trial, with storage, monthly credits, and workspaces scaled to each plan.

A typical agent team workflow with persistent storage:

1. Lead spawns teammates to work on different modules
2. Each teammate writes code, tests, and documentation to the local repo
3. Lead synthesizes the work, resolves conflicts, and creates a final package
4. Lead uploads the deliverable to a shared workspace via MCP
5. Human reviewers access the workspace through the web UI, with Intelligence Mode providing semantic search across all uploaded files

Agents connect through the Fast.io MCP server at mcp.fast.io, which exposes 19 consolidated tools for workspace, storage, AI, and workflow operations. The server supports Streamable HTTP at /mcp and legacy SSE at /sse, and works with any agent framework that supports the Model Context Protocol.

The handoff pattern is the core value for agent teams. Teammates build something collaboratively, the lead packages it, and a human picks up the result in a workspace that already understands the content. No manual file sorting, no re-reading everything from scratch.