Claude Code Multi-Agent Orchestration: 2026 Guide

One Claude Code session can already handle meaningful engineering work. Several of them can be used to review a PR from three angles at once or chase five debugging hypotheses simultaneously. The catch is that "run multiple agents" means three different things in 2026, with different setups, costs, and ceilings. This guide maps all three. There are subagents within a single session, the built-in Agent Teams feature for parallel teammates on a single machine, and external orchestrators for running Claude Code across repos and a whole team. You'll get the actual setup for Agent Teams and a clear sense of when to reach for each level.

What is multi-agent orchestration in Claude Code?

Multi-agent orchestration in Claude Code means coordinating multiple Claude instances so they divide a task, work in parallel, and combine their results, rather than a single session doing everything sequentially. Anthropic ships two built-in mechanisms for this, subagents and Agent Teams, and a third tier of external tools handles coordination at team and repository scale (this is what we built Tembo for!).

The reason to care is parallel exploration. A single agent investigating a bug tends to find one plausible cause and stop; three agents, when told to challenge each other's theories, converge on the real cause faster. The same logic applies to code review, where one reviewer drifts toward a single class of issues, whereas three reviewers can cover security, performance, and tests at once. Orchestration is how you turn one capable agent into a small, coordinated team.

The three orchestration modes

Before any setup, get the mental model right, because picking the wrong mode is the most common mistake. The three modes trade coordination for cost in increasing order.

Subagents

Subagents run inside a single Claude Code session. The main agent spawns focused helpers for a piece of research or verification; each works in its own context window, and each reports its result back to the main agent. They never talk to each other. Because results are summarized back into the main context, subagents are the cheaper option, and they're the right choice when you only care about the answer, not the deliberation. We cover them in depth in our Claude Code subagents guide.

Agent Teams

Agent Teams is the newer built-in feature, and it's a genuine step up in coordination. One session acts as the team leads, coordinating work and synthesizing results, while teammates run as separate Claude Code instances that each have their own context window and message each other directly through a shared task list. The trade-off is cost. Each teammate is a full Claude instance, so a team uses significantly more tokens than a single session. Agent Teams is the mode you set up below.

External orchestrators

The third tier sits above Claude Code entirely. External orchestrators are tools that run and coordinate Claude Code sessions across machines, branches, and repositories, adding dashboards, git-worktree tracking, and governance that the built-in features don't cover. Tools like Gas Town, Conductor, and Multiclaude live here, and so does Tembo, which runs Claude Code as a background agent across your repos and triggers it from Slack, Linear, or GitHub. This is the tier you reach for when orchestration stops being a one-machine problem and becomes a team one.

How to set up Claude Code Agent Teams

Agent Teams is experimental and disabled by default, so setup is a short, deliberate process. The setup, limitations, and flag details below are based on Anthropic's Agent Teams documentation. It requires Claude Code v2.1.32 or later, which you can confirm first.

claude --version

1. Enable the feature. Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS variable to 1, either in your shell or in settings.json. Note the value is 1, not true.

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

2. Create the team in natural language. You don't script the team; you describe it. Tell Claude what you want and let it spawn the teammates and the shared task list.

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Claude creates the team, assigns work, and coordinates the teammates based on your prompt. Importantly, it won't create a team without your approval, so you stay in control of when one spins up.

3. Watch and steer. Agent Teams has two display modes, and the default setting is auto: you get split panes if you're already inside a tmux session or using iTerm2, and in-process mode otherwise. In in-process mode, every teammate runs in your terminal. Press Shift+Down to cycle through teammates and message any of them directly, Enter to view a teammate's session (Escape interrupts their current turn), and Ctrl+T to toggle the shared task list. If you'd rather see everyone at once, split-pane mode gives each teammate its own pane — this requires tmux, or iTerm2 with the it2 CLI and its Python API enabled. To pin a mode instead of relying on auto-detection, set teammateMode in ~/.claude/settings.json ("tmux" forces split panes, "in-process" keeps everything in one terminal), or override per session with claude --teammate-mode in-process.

{
  "teammateMode": "in-process"
}

Behind the scenes, a team is a lead plus teammates coordinating through a shared task list and a mailbox, with team and task state stored under ~/.claude/teams/ and ~/.claude/tasks/. Those files are generated automatically, so don't hand-edit them.

For risky work, you can require teammates to plan before they touch code. The teammate stays in read-only plan mode until the lead approves its approach, which is a useful gate when the change is large or sensitive.

If teammates don't appear after you ask for a team, press Shift+Down in in-process mode to cycle through the active ones, since they may be running but not visible. And if a tmux session lingers after a team ends, clean it up directly:

tmux ls
tmux kill-session -t <session-name>

Where Agent Teams pays off

Two patterns from Anthropic's own examples show why parallel teammates beat one session for the right work. The first is a multi-lens code review, where one prompt spins up reviewers who each apply a different filter:

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

The lead synthesizes the three findings into a single review, so nothing falls through the cracks that a single reviewer might miss. The second is adversarial debugging. When a root cause is unclear, you spawn several teammates to investigate competing hypotheses and try to disprove each other, like a scientific debate. The theory that survives the cross-examination is far more likely to be the real cause than the first plausible answer a single agent would have settled on.

Orchestrating Claude Code across repos and teams

Agent Teams does a lot, but it has a deliberate boundary. It coordinates instances on one machine, one team at a time, with the lead fixed for the team's lifetime and no nested teams. That boundary is fine for an individual developer parallelizing a task. It's the wrong shape for a team that wants Claude Code to run across several repositories, be triggered by tickets, and have shared visibility and approvals.

That's the gap external orchestration fills, and it's where Tembo operates. Instead of you opening a terminal and enabling a flag, a change request arrives as a Slack message or a Linear ticket. Tembo runs Claude Code (or Cursor, or Codex) as a background agent against the relevant repos, and a reviewed pull request comes back. The coordination that Agent Teams does within a single terminal, an external orchestrator does across your whole codebase and team, including multi-repo changes that span services in a single coordinated pass. Sensitive code can run self-hosted in your own VPC.

The two layers complement each other rather than compete. A developer uses Agent Teams to parallelize their own work in the moment; a team uses an orchestration layer to run agents continuously across the org with governance. If you're mapping out the latter, our agentic orchestration and coding agent orchestration guides cover the architecture, and the run Claude Code in parallel guide covers the manual git-worktree approach that sits between subagents and a full platform.

Best practices for Claude Code teams

A few habits separate a productive team from an expensive mess, and most come straight from how the feature behaves under load.

• Start with 3-5 teammates. That range balances real parallelism against coordination overhead, and beyond it, you hit diminishing returns. Three focused teammates usually beat five scattered ones.
• Size tasks as self-contained units. A function, a test file, a single review. Aim for roughly 5-6 tasks per teammate so the lead can reassign work if someone stalls.
• Give each teammate different files. Two teammates editing the same file overwrite each other, so partition the work by file ownership.
• Lead with research and review. PR reviews and bug investigations show off parallel exploration without the coordination risk of parallel writes, which makes them the best first use.
• Mind the token bill. Each teammate is a separate context window, so cost scales with team size. Reserve teams for work that genuinely benefits from parallelism.
• Use CLAUDE.md and hooks for guardrails. Teammates automatically load your project's CLAUDE.md, and hooks like TaskCompleted can enforce a quality gate before a task is marked as done. A good CLAUDE.md does more work as you add agents.

The takeaway: match the mode to the scope

Claude Code multi-agent orchestration is really a question of scope. For a focused subtask, use subagents. To parallelize your own work across a problem, set up Agent Teams with the flag above. To run Claude Code continuously across repositories and a team with approvals, reach for an external orchestrator. Each tier adds coordination and cost, so use the smallest one that fits the job.

When the job outgrows a single terminal, try Tembo's free tier and run Claude Code as a background agent across your repos, triggered from the tools your team already works in.

FAQ

What is the difference between Claude Code subagents and Agent Teams? Subagents run inside one session, and only report results back to the main agent; they never communicate with each other and cost less. Agent Teams are separate Claude Code instances that share a task list and can message each other directly, which suits collaborative work but incurs higher token costs. Use subagents when only the result matters, and teams when the agents need to discuss and challenge each other.

How do I enable Claude Code Agent Teams? Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your shell or settings.json, on Claude Code v2.1.32 or later. Then ask Claude in natural language to create a team for your task. The feature is experimental and off by default.

Can I run Claude Code agents across multiple repositories? Not with the built-in Agent Teams feature, which works on a single machine and team at a time. Multi-repo coordination is the job of an external orchestrator like Tembo, which runs Claude Code across repos and returns linked pull requests.

Does Agent Teams work in the VS Code terminal? In-process mode works in any terminal, including VS Code's. Split-pane mode does not work in the VS Code integrated terminal, Windows Terminal, or Ghostty; it needs tmux or iTerm2.