Multi-Agent Orchestration: Coordinating Teams of Claude Sessions

Why One Agent Has a Ceiling

A single Claude session has one context window. Every file it reads, every command it runs, every message you exchange fills that window. For a focused task — fix this bug, write this function — one session is exactly right. But for large, parallel, or multi-perspective work, one context window becomes a bottleneck.

Consider a thorough code review of a large PR. A single reviewer tends to find the type of issue they're looking for first and then gravitates toward similar issues, missing whole categories. Put three reviewers on it simultaneously — one focused on security, one on performance, one on test coverage — and you get qualitatively different results. Claude Code's multi-agent features bring this same logic to AI-assisted development.

Subagents: The Right Starting Point

Subagents are the simpler, more token-efficient form of delegation. When you ask Claude to "use a subagent to investigate how our auth system handles token refresh," it spawns a helper agent that:

• Runs in its own separate context window
• Reads files, runs searches, executes commands independently
• Returns a summary of its findings to your main session
• Leaves your main context clean — only the findings come back, not all the file reads the subagent did

This is the key value: subagents keep your main context from filling up with exploratory noise. Instead of Claude reading 40 files in your session, a subagent reads 40 files in its own context and hands you back a two-paragraph summary.

You can also define custom subagents in .claude/agents/ to give them a specific role, toolset, and model. A security-reviewer subagent always looks for injection vulnerabilities, auth flaws, and hardcoded secrets. A test-writer subagent always outputs pytest files. These definitions travel with your repository:

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- SQL injection, XSS, and command injection
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling and missing input validation

Provide specific line references and suggested fixes with severity ratings.

Invoke it with: "Use a subagent to security-review the new payment handler."

Subagents can also run in isolated git worktrees to prevent file conflicts during parallel edits. Add isolation: worktree to your subagent definition's frontmatter and each spawned subagent gets its own branch and directory automatically.

Agent Teams: When Subagents Need to Talk to Each Other

Subagents only report results back to the main agent — they never communicate with each other. For tasks where the workers need to share findings, challenge each other's conclusions, or coordinate on a shared task list, Claude Code offers Agent Teams.

Agent Teams are more powerful but also more experimental. As of 2026, they are disabled by default and must be explicitly enabled:

# .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Requires Claude Code v2.1.32 or later. Check your version with claude --version.

With Agent Teams enabled, one session acts as the team lead. It creates a team, spawns teammates, and coordinates through a shared task list. Teammates have their own context windows and their own sessions — they can message each other directly, not just report back to the lead. This is the architectural difference that matters:

• Subagents — like remote workers who send you a status report when done. You manage all coordination.
• Agent Teams — like a room of people who can talk to each other, claim tasks from a shared board, and challenge each other's work. The lead manages the team; the team manages itself.

To start a team, describe the task and the team structure you want in natural language:

"Create an agent team to review PR #142. Spawn three reviewers: one focused on security implications, one checking performance impact, one validating test coverage. Have them each review and report findings."

Claude creates the team, spawns teammates, and assigns tasks. Use Shift+Down to cycle through teammates in your terminal and type directly to any one of them.

Practical Orchestration Patterns

Pattern 1: Parallel code review with independent lenses

This is the strongest agent team use case. A single reviewer anchors on one type of issue. Three independent reviewers with distinct mandates cover the space far more thoroughly:

"Create an agent team to review the new file upload handler. One teammate focused on security (injection, path traversal, MIME validation). One teammate on performance (memory usage, streaming vs buffering, concurrency). One teammate on correctness (error handling, edge cases, test coverage). Synthesize all findings."

Pattern 2: Competing hypothesis debugging

When a bug's root cause isn't obvious, one agent tends to find a plausible explanation and stop exploring. Multiple agents explicitly tasked with disproving each other find the real cause faster:

"Users report the app disconnects after exactly one message. Spawn 4 agent teammates to investigate different theories: session timeout misconfiguration, WebSocket keepalive failure, load balancer idle timeout, and memory leak causing GC pauses. Have them challenge each other's theories and converge on a finding."

Pattern 3: Parallel new feature modules (subagents with worktree isolation)

When building independent pieces of a feature — frontend component, backend handler, database migration — spawn subagents with isolation: worktree so they work on separate branches simultaneously and you merge when done.

Token Costs and Team Size

Agent teams use significantly more tokens than a single session. Each teammate has its own context window and consumes tokens independently — costs scale linearly with the number of active teammates. Three teammates costs roughly three times as much per unit time as one session.

The Anthropic recommendation based on real-world usage: start with 3–5 teammates. This range balances parallel throughput with manageable coordination overhead. Give each teammate 5–6 tasks to keep them productive without too much context switching. More teammates rarely produce proportionally better results — they produce more coordination overhead.

Known Limitations to Plan Around

Agent Teams are experimental. These are real limitations as of 2026, not theoretical ones:

• No session resumption for in-process teammates — /resume does not restore teammates. After resuming a lead session, in-process teammates no longer exist. Spawn replacements.
• Task status can lag — teammates sometimes fail to mark tasks as completed, which can block dependent tasks. If a task appears stuck, verify manually and nudge the lead or teammate directly.
• Split-pane mode requires tmux or iTerm2 — in-process mode works in any terminal. Split-pane mode (separate pane per teammate) is not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.
• No nested teams — teammates cannot spawn their own teams. Only the lead manages the team.

For production-critical work, subagents remain the more reliable choice. Use agent teams when the coordination model genuinely adds value — parallel review, competing hypotheses, independent module development — and when you can monitor the session.