Agent Teams & Orchestration at Scale

One Claude in one terminal is the default, and for most work it is enough. But some tasks fight that shape. A migration touches two thousand files. A bug has four plausible causes and chasing them one at a time means three dead ends in series. A pull request needs a security pass, a performance pass, and a test-coverage pass — and a single reviewer tends to fixate on whichever one it noticed first.

These are fan-out problems: independent work that wants to happen at the same time. This guide is about the tools Claude Code gives you to run more than one agent at once, how they differ, and — just as important — when reaching for them is a mistake. We will be precise about what is a shipped Claude Code feature, what is experimental, and what is an Agent SDK or orchestration pattern you build yourself. Overclaiming here wastes tokens and trust.

When one agent is not enough

A single session is the right tool until two things become true at once: the work splits cleanly into pieces that do not depend on each other, and keeping it all in one context window would either overflow it or slow it down. Reading a hundred files to answer one question pollutes the context you need for the actual edit. Running four debugging theories sequentially anchors the second on whatever the first found. When you hit that wall, you stop scaling the prompt and start scaling the number of agents.

The flip side matters more. Coordinating agents is not free — every extra agent is extra tokens, extra communication, and extra chances for two of them to edit the same file and clobber each other. If the work is sequential, shares state, or could be one tight prompt, more agents make it slower and worse, not faster. The skill is recognizing which kind of problem you actually have.

Subagents: delegation inside one session

A subagent is the lightest form of parallelism, and usually the first one you should reach for. You ask the main agent to delegate — "use a subagent to investigate how token refresh works" — and Claude spawns a helper that runs in its own context window, reads whatever files it needs, and returns only a summary. The hundred file reads happen in the subagent's context; your main conversation receives the findings and stays clean.

The defining constraint of a subagent is its communication shape: it reports results back to the main agent and only the main agent. Subagents do not talk to each other. The orchestrator dispatches them, collects what comes back, and decides what happens next. That makes them perfect for focused, independent jobs where only the result matters — codebase research, an adversarial review of a diff, generating a batch of test cases.

You can use them ad hoc by just asking, or define reusable ones as markdown files in .claude/agents/. A definition pins the subagent's name, description, allowed tools, and model in frontmatter, with a system prompt in the body — for example a security-reviewer restricted to Read, Grep, Glob, Bash. Once defined, you invoke it by name. Add isolation: worktree to a subagent's frontmatter and each invocation runs in its own throwaway git worktree, so several subagents can edit in parallel without conflicts.

Background sessions: dispatch and monitor with agent view

Subagents live inside one conversation. Sometimes you want several full, independent Claude Code sessions running at once — a bug fix here, a PR review there, a flaky-test investigation in a third — without babysitting each in its own terminal. That is what agent view is for. Run claude agents and you get one screen that lists every background session, grouped by state: which are Working, which Need input, which are Completed or Failed.

Each background session is a real Claude Code conversation that keeps running without a terminal attached. From agent view you type a prompt to dispatch a new session, press Space to peek at a row's latest output (or the question it is blocked on) and reply inline, or press Enter to attach and take over the full conversation. You can also background a session you already have open by running /bg inside it. This is the answer to "how do I monitor a long run": you are not staring at a scrolling transcript, you are watching state icons and stepping in only on the rows that turn yellow.

Two honest caveats. Agent view is a research preview (it requires a recent Claude Code version, and its shortcuts may change), and each background session draws on your usage quota independently — dispatch ten and you are paying for ten. Note also that subagents and agent-team teammates a session spawns do not show up as their own rows here; agent view tracks top-level sessions, not the helpers inside them.

Agent teams: coordinated sessions that talk to each other

Subagents cannot talk to each other, and background sessions do not share a task list. Agent teams close that gap — and they are explicitly experimental and disabled by default. You turn them on by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your environment or settings.json, and they require a recent Claude Code version. Treat this as a feature still finding its shape, not a stable foundation.

The model is one team lead plus several teammates. The lead is the session you started; it spawns teammates, breaks the work into a shared task list, and synthesizes results. Each teammate is a full, independent Claude Code session with its own context window — and crucially, teammates can message each other directly through a shared mailbox, claim tasks off the list (file locking prevents two of them grabbing the same one), and challenge each other's findings. You can talk to any teammate directly instead of routing everything through the lead.

That direct communication is the whole point, and it dictates when teams earn their cost. They shine where parallel exploration adds value and workers need to compare notes: a parallel PR review with one teammate per lens, or a bug investigation where five teammates each push a competing hypothesis and try to disprove the others — a structure that beats sequential debugging precisely because it resists anchoring. The official guidance is to start with 3–5 teammates and lean on research and review tasks before parallel implementation. Teams cost significantly more tokens than a single session, so for sequential work, same-file edits, or anything with heavy dependencies, a single session or plain subagents win.

Deterministic orchestration vs. autonomous teams

There is a deeper fork here than which feature to use. On one side is deterministic orchestration: you own the control flow. The clearest example is fan-out with non-interactive mode — generate a list of files, then loop a script that calls claude -p "migrate $file" once per file, scoping each run with --allowedTools so it can only do what you intend. Nothing is left to a model's judgment about who does what; the orchestration lives in your shell script, runs the same way every time, and is trivial to retry. The same determinism shows up in the Writer/Reviewer pattern (one session writes, a fresh one reviews) and in piping claude -p output into the next command of a pipeline.

On the other side is autonomous coordination: you hand a goal to a lead — human or agent — and let it decide how to split the work, who does what, and when the team is done. Agent teams sit here. So does asking a single session to "use subagents to figure out the best approach." This buys flexibility for fuzzy, exploratory problems where you cannot script the steps in advance, at the price of predictability and tokens. Neither end is better; the rule of thumb is to push work toward the deterministic end whenever the steps are knowable, and reserve autonomy for the genuinely open-ended.

If you want orchestration in code rather than a shell loop, that is the Agent SDK (Python and TypeScript). It exposes the same agent loop as Claude Code as a library: a query() call drives an agent, and you define subagents programmatically by passing AgentDefinitions in the agents option, building the orchestrator-worker pattern yourself with full control over tools, permissions, and sessions. The CLI is for interactive and one-off work; the SDK is for production automation and custom apps. They are two interfaces to the same engine — do not confuse the SDK's programmable orchestration with the CLI's built-in agent-teams feature.