Orchestrating Agent Teams

One Agent Is Not Always Enough

Single Claude Code sessions can do impressive things. But some problems are just too big. A security review requires a completely different mindset than a performance review. Building a frontend and backend simultaneously means two unrelated file sets. Debugging a flaky test might benefit from three competing hypotheses explored at the same time.

Agent teams let multiple Claude Code instances work in parallel, each with its own context, coordinating through a shared task list and direct messaging.

Fair warning: this is experimental. Enable it with an environment variable before launching:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

How Teams Differ from Subagents

Subagents (from the previous lesson) run inside your session. They do a focused task and report back. Quick errands.

Agent teams are a different animal. Each teammate is a fully independent Claude Code instance. Own context window. Own file access. Own conversation history. Teammates can message each other directly, not just report to a coordinator. They share a task list, and they run truly in parallel.

The trade-off is simple. Subagents are lightweight and cheap. Agent teams are heavier (token costs scale linearly with each teammate) but can tackle problems that'd overwhelm a single context window.

Architecture of a Team

Every team has a team lead, the Claude Code instance you interact with. It coordinates work, spawns teammates, and reviews output.

Teammates are separate instances the team lead creates, each with a spawn prompt describing its focus area. They communicate through two channels: a shared task list and a mailbox for direct messages.

Tasks have states (pending, in progress, completed) and you can set up dependencies between them. The team lead either assigns tasks to specific teammates or lets them self-claim from the pending pool. There's also an option to require plan approval before implementation starts, giving you a checkpoint to course-correct early.

Configuration lives in ~/.claude/teams/{team-name}/config.json, task state in ~/.claude/tasks/{team-name}/.

Viewing and Managing Teams

Two display modes. In-process mode keeps everything in one terminal where you press Shift+Down to cycle between teammates. Fine with two or three, gets crowded beyond that.

Split pane mode uses tmux or iTerm2 to give each teammate its own pane. Way better for watching everyone at once. If you already use tmux, this'll feel natural.

You can message any teammate directly from the team lead session. See one going off the rails? Send it a correction without disrupting the others. Reassign tasks, add new ones, mark things as blocked, all on the fly.

When to Use Teams

Not every problem benefits from parallelism. Teams earn their keep in specific patterns:

Research and review is the most natural fit. Three reviewers on one PR: security, performance, test coverage. Same code, completely different lenses, running simultaneously.

Building independent modules works when the pieces don't share files. One teammate on the API, another on the React components, as long as they agree on the interface contract up front (define it in the spawn prompt).

Debugging with competing hypotheses is surprisingly effective. Three plausible theories about a bug? Spawn three teammates. First one to find the root cause wins. Way faster than testing hypotheses sequentially.

Cross-layer coordination handles changes spanning database, backend, and frontend. Each layer gets a teammate. The shared task list keeps dependencies clear so nobody builds UI for an endpoint that doesn't exist yet.

Try It

Suppose you have a PR that touches authentication, database queries, and API response handling. Ask your team lead:

Create an agent team called "pr-review" to review PR #142.
Spawn three reviewers:
- Reviewer 1: focus on security — auth flows, input validation, token handling
- Reviewer 2: focus on performance — database queries, N+1 problems, caching
- Reviewer 3: focus on test coverage — missing edge cases, error paths, integration gaps

Each reviewer should file their findings as completed tasks.

The team lead creates the team, spawns three teammates, sets up the task list. Each reviewer works through the diff independently, findings accumulate for you to review.

If that feels like a lot, start smaller. Two teammates, different files. One writes tests, the other refactors. Get comfortable with the coordination flow before scaling up.

Practical Guidelines

Three to five teammates is the sweet spot. Beyond that, coordination overhead and token costs eat the parallelism benefits. Give each teammate roughly five to six tasks.

The spawn prompt matters enormously. Each teammate needs to know what it owns, what files it should touch, and what it should stay away from. Vague spawn prompts lead to teammates stepping on each other or duplicating work. Two teammates editing the same file simultaneously means conflicts. Plan your boundaries around file ownership.

Monitor actively. The team lead session is your command center. Check in, read messages, steer when needed. Think of yourself as a tech lead running a sprint, not a manager who delegates and walks away.

And remember: this is experimental. Expect rough edges. Check the Claude Code docs for current syntax, because it's evolving fast.