Agent Teams in Claude Code: How They Work, When They Break, and What Comes Next

Anthropic shipped agent teams alongside Opus 4.6 today. If you missed it in the announcement, here's the short version:

You can now spin up multiple Claude Code instances that coordinate through a shared task list and work in parallel.

On the same day, Anthropic's Nicholas Carlini published a post about using 16 parallel Claude agents to build a C compiler from scratch: 2,000 sessions, $20,000 in API costs, 100,000 lines of Rust. That post is the best stress test of this primitive that exists right now, and I'll reference it throughout.

Agent teams are still experimental, the docs are thin, and the gap between "multiple Claudes working together" and "multiple Claudes working together productively" is wide.

Here's what we’ve found so far.

What are agent teams?

Agent teams sit on top of Claude Code's existing primitives (subagents, custom agents, CLAUDE.md files) but they work differently from all of them.

One Claude Code session becomes the team lead. It creates a shared task list, spawns teammates, and coordinates results. Each teammate runs in its own context window and works independently. When teammates finish, they report findings back through an inbox system, and the lead synthesizes everything.

To enable the feature, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment or settings.json.

After that, you describe the team structure in natural language and Claude handles the spawning.

Here's the example from the docs:

I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.

Claude creates the team, spawns three teammates, gives each a perspective, and synthesizes their findings when they're done. You can interact with individual teammates directly using Shift+Up/Down to cycle between them, or run in tmux for split-pane visibility. That "explore from different angles" framing is deliberate.

The docs recommend starting with tasks that have clear boundaries and don't require writing code: reviewing a PR, researching a library, investigating a bug. These are read-heavy, parallel-friendly tasks where agents can work without stepping on each other.

How this differs from what Claude Code already had

Claude Code already supports parallel work through a few different mechanisms, and agent teams add a coordination layer on top.

Subagents run inside a single Claude Code session. They inherit the parent's context, do a task (research a question, verify a fact, run a specific check), and report back to the main agent. They can't talk to each other, and you can't interact with them directly. They work well for delegation within a single conversation, but not for parallel exploration across independent contexts.

Custom agents are specialized roles you define in .md files: a code reviewer, a security auditor, a documentation writer. Claude invokes them based on task fit. Each gets its own system prompt, tool access, and optionally a specific model (Opus, Sonnet, Haiku). They're powerful for specialization, but they still run one at a time within a single session.

Manual worktrees are the DIY version. You open multiple terminal tabs, check out separate Git worktrees, and run independent Claude Code sessions in each one. You get full context isolation and parallel execution, but you're the coordinator. This is what a lot of power users already do for parallel work, and it works well if you don't mind managing the merges yourself.

Agent teams add automated coordination on top of parallel sessions. The team lead manages a shared task list, teammates communicate through inboxes, and you can monitor everyone from one place. The tradeoff: you give up some control in exchange for not having to manually orchestrate across tabs.

Subagents and custom agents are single-session primitives. Manual worktrees and agent teams are multi-session primitives. Context isolation (each session having its own window) makes true parallel work possible, but also makes coordination hard.

The C compiler version is a different harness

One thing that confused us initially: the agent teams feature shipping in Claude Code today and the setup Carlini used for the C compiler project are related but not identical.

Carlini's harness is more bare-bones. He spins up Docker containers, each with its own clone of a shared bare git repo. Each agent runs in an infinite loop: finish a task, push changes, pull from upstream, pick the next task. Coordination happens through git's own conflict resolution and a lock file system where agents claim tasks by writing to current_tasks/. There's no orchestration agent or inbox system. Each Claude just decides what to work on next.

The Claude Code agent teams feature adds more structure: a team lead role, explicit task assignment, inter-agent messaging, and the ability to interact with individual teammates without stopping the team. But both approaches share the same core idea: multiple Claude instances, each with independent context, working on a shared codebase.

Carlini's version ran 16 agents for two weeks and produced a compiler that can build Linux 6.9. Claude Code features a research preview with known limitations around session resumption, task coordination, and shutdown behavior. The primitive works, but the shipping feature is still a research preview.

If you've been following Steve Yegge's Gas Town framework, agent teams cover similar ground with a simpler coordination model: one lead, N workers, inbox messaging.

Gas Town uses a more elaborate role hierarchy (mayor, polecats, witnesses) and has been in use longer.

Both are trying to solve the same problem: how do you coordinate multiple Claude instances working on a shared codebase?

Agent teams bake a minimal version of this into Claude Code itself rather than requiring an external harness.

When do agent teams work?

Based on 24 hours of use, we found Agent Teams have a narrow sweetspot: tasks where multiple agents can explore a problem in parallel, mostly by reading, without needing to write to the same files.

Read-heavy parallel exploration

The strongest use case is when you have a question with multiple angles, and each angle can be explored independently. We call it multi-perspective investigation.

Code review from multiple perspectives. You're reviewing a large PR and want a security audit, a performance review, and an architectural assessment happening simultaneously. Each agent reads the diff, checks different things, and reports findings to the lead. The agents never conflict because they're all reading, but not writing code.

Bug investigation. You have a production error and don't know where to start. One agent traces the stack trace through the codebase, another checks recent commits that touched the relevant modules, a third reads the test suite for coverage gaps. Each agent narrows the search space, and the lead synthesizes a hypothesis from their findings.

Library evaluation. You're choosing between three ORMs for a new service. Each agent evaluates one: reads the docs, checks GitHub issues, looks at the API surface, assesses compatibility with your stack. Instead of serial research, you get three parallel evaluations that the lead can compare.

The team lead synthesizes perspectives you'd otherwise read and compare yourself.

How to structure tasks so agents don't collide

The moment agents start writing code, you need to think about file boundaries.

Anthropic's docs are direct about this: two teammates editing the same file leads to overwrites. The lead assigns work rather than merging results, so you need to break work into units where each agent owns distinct files.

Module-per-agent. If you're building a CLI tool, one agent writes the argument parser, another writes the core logic, a third writes the output formatter. Each agent owns a directory or file and doesn't touch the others. This is roughly how Carlini structured the C compiler. Agents worked on separate compiler passes (lexer, parser, code generator) and pushed changes independently.

Test-per-agent. You have ten modules that need test coverage. Each agent gets assigned a module and writes tests for it. The files are naturally separated because each module has its own test file. This is close to "embarrassingly parallel" because agents are interchangeable and can self-assign from a queue.

Spike-per-agent. You're prototyping three different approaches to the same problem. Each agent works in its own branch or directory, building a proof of concept. You compare the results and pick one. The agents never touch shared code because each approach is isolated by design.

The common thread: you need to decompose the work before spawning the team, and the decomposition needs to produce units with clear file boundaries. If you can't draw those boundaries cleanly, agent teams will fight over files, and right now there's no merge resolution built into the coordination layer.

So what did $20,000 and 16 agents actually produce?

Carlini's C compiler experiment is the most ambitious test of parallel Claude agents that exists, and it shows the real ceiling of this approach with current models.

What worked? 16 agents, each running in a Docker container with its own git clone, built a Rust-based C compiler from scratch over about two weeks. The result compiles real-world C code, including the Linux 6.9 kernel for x86, ARM, and RISC-V. Without being told to, agents self-organized into roles: deduplication, performance, code quality, documentation.

How much did it cost? 2,000 Claude Code sessions, roughly 2 billion input tokens, and $20,000 in API spend. The compiler is 100,000 lines of Rust.

Is it actually good? Carlini is honest about this: the generated code is less efficient than GCC with optimizations disabled. The compiler proves the approach works, but nobody's shipping code with it. The internet claims the compiler is brittle - thus we need more time to tell whether it’s good or not.

What challenges did he face working with multiple agents?

Agent Collisions: When multiple agents hit the same failing test during the Linux kernel compilation, they all tried to fix it simultaneously and overwrote each other's changes. Carlini had to build a custom oracle-based test harness that split test cases so agents would encounter different failures. The same file conflict the docs warn about, playing out across 16 agents at once. The solution required custom infrastructure outside of Claude Code itself.

Context Rot: Context windows filled up fast. Test output from a full compiler run can flood the context with thousands of lines of irrelevant diagnostics. Carlini built --fast flags that run random subsamples of tests so agents could check their work without burning their entire context on output. Claude also can't tell time, so agents would happily run a full test suite for hours without realizing they were blocked. The --fast flags doubled as a time management hack.

What did Carlini prove about agent teams: The compiler experiment proves that parallel Claude agents can produce real, working software at non-trivial scale. It also shows that the coordination problems (file conflicts, context pollution, unbounded execution) don't disappear when you throw more agents at them; they multiply. Every solution Carlini built (the oracle test harness, the --fast flags, the task lock files) was custom infrastructure built to solve problems the agents couldn't solve on their own.

Where agent teams break down

Section 2 covered the file conflict and context pollution problems through the lens of Carlini's compiler experiment. Those are real, but they're also the obvious failure modes. The structural limitations of agent teams as a coordination primitive are more interesting, because they're not bugs waiting to be fixed. They follow directly from how the feature works.

Agent collisions

When multiple agents work on the same codebase independently, they tend to notice the same things. In the compiler project, agents would all encounter the same failing test during a Linux kernel compilation and independently try to fix it. Carlini's solution was a custom oracle that split test cases so agents would hit different failures.

This isn't specific to compilers. If you spin up a team to investigate a production bug, there's a good chance multiple teammates will trace the same stack trace to the same root cause and file near-identical reports. The lead then has to deduplicate rather than synthesize. You spent tokens on three agents but got one answer.

So what’s the underlying issue? Agent teams don't have a mechanism for teammates to check what others are already working on in real time. The inbox system lets them report findings after completing work, but there's no shared state that prevents duplicate effort during work. Carlini solved this with lock files in current_tasks/. The Claude Code feature relies on the team lead's judgment to assign non-overlapping work upfront, which works well for clearly decomposable tasks and poorly for investigation where the right decomposition isn't obvious until you're mid-exploration.

Supervising agents

Anthropic's own docs include this line: "Letting a team run unattended for too long increases the risk of wasted effort". That's a carefully worded way of saying agent teams need babysitting.

Each agent drifts independently, and the drift compounds. In a single Claude Code session, you can watch the agent's reasoning and course-correct when it goes off-track. With a team of four agents running in parallel, you're monitoring four streams of work simultaneously.

You can cycle between teammates with Shift+Up/Down, but you can only read one at a time. If teammate #3 goes down a rabbit hole while you're reviewing teammate #1's findings, you won't notice until #3 reports back with wasted work.

Agent teams exist to parallelize work, but monitoring parallel work is inherently harder than monitoring serial work. The more agents you add, the more supervision overhead you take on. Carlini's 16-agent setup required building automated test infrastructure specifically to catch agents that were spinning. For a three-agent team reviewing a PR, the overhead is manageable. For anything larger or longer-running, you need external structure to keep agents on track.

Single model per session

Agent teams don't support per-teammate model selection, rather every teammate uses the same model.

If your session runs Opus, every teammate runs Opus. If it runs Sonnet, every teammate runs Sonnet. This gets expensive quickly.

Different tasks within a parallel workflow have very different intelligence and cost profiles. Planning tasks benefit from a strong model that can reason about architecture. Tasks that grep through a codebase counting function signatures don't need Opus-level reasoning and shouldn't cost Opus-level tokens. A security review probably wants the strongest model available, while a formatting check could run on Haiku.

In the compiler experiment, every agent ran the same model for every type of work: planning, implementing, testing, debugging, documenting. Carlini's $20,000 bill reflects this. Some of that spend went toward Opus-level reasoning for tasks that could have been handled by a cheaper model, and there's no way to optimize that within the current agent team’s design.

Custom agents in Claude Code do support per-agent model selection (you specify the model in the agent's .md definition). But custom agents are single-session primitives. Agent teams, which give you parallel execution, don't give you model flexibility, so you currently have to choose.

For API users, this is a cost optimization problem. For Pro subscription users, it's a rate limit problem: agent teams multiply token consumption with no way to route cheaper tasks to cheaper models. A three-agent team burns through your daily allocation roughly three times faster, and every teammate consumes Opus tokens whether the task warrants it or not.

No checkpoints or approval gates

The bottleneck in multi-agent work is validation. Running four agents simultaneously is easy. Knowing whether each agent's output is correct before the next agent consumes it is the hard part, and agent teams have no structural answer for it.

When a workflow runs through agent teams, progress depends entirely on the model's judgment about when a task is "done." There's no mechanism to insert a validation step between phases of work, like "confirm the bug is actually reproduced before starting the fix" or "run the test suite before moving to documentation."

In a single Claude Code session, you can approximate this by being present and saying "wait, check this before continuing." With agent teams, you'd need to monitor each teammate's progress and manually intervene at the right moment. For a three-agent PR review, that's fine because the task is inherently one-shot: each agent reviews and reports. For a multi-phase task like bug reproduction (reproduce, then debug, then fix, then test), there's no structural way to enforce "don't start debugging until reproduction is confirmed."

The team lead coordinates task assignment, but it doesn't validate task completion. A teammate says "done" and the lead trusts it. If the reproduction agent reports "bug reproduced" but actually reproduced something slightly different, the debug agent proceeds on a false premise and the error compounds through every subsequent step. Adding more agents doesn't help here. It makes validation harder because there are more handoffs to check.

Visibility is terminal output across tmux panes

The monitoring interface for agent teams is tmux. You split your terminal into panes, one per teammate, and watch the output scroll. As mentioned before, can also cycle between teammates within a single pane using Shift+Up/Down.

For a short-lived team of two or three agents doing read-only work, this is adequate. For anything longer or more complex, you're watching multiple streams of unstructured text and trying to hold the state of each agent in your head. There's no summary view of "agent 1 is 60% through its task, agent 2 is blocked on a failing test, agent 3 finished and reported findings." You have to read the raw output and figure that out yourself.

Carlini's compiler setup had the same visibility challenge at a much larger scale (16 agents). His solution was to watch git commit messages and task lock files to infer what agents were doing. He built external tooling to track progress because the agents themselves didn't provide structured status updates.

Terminal output shows you what agents are producing, but not which step they're on, what's passed validation, or what's blocked. That kind of structured execution tracking doesn't exist in agent teams yet.

What’s the value of structured orchestration?

Agent teams sit at one point on a coordination spectrum.

On one end, subagents: single-session helpers that do a task and report back. On the other end, explicit workflow definitions where every agent, sequence, checkpoint, and model choice is specified upfront. Agent teams land in the middle: multi-session parallelism with coordination through model judgment.

The limitations from section 3 (convergence, supervision, single model, no checkpoints, terminal visibility) all trace back to the same design choice: agent teams coordinate through the team lead's reasoning rather than through explicit structure. That choice buys you flexibility.

You describe what you want in natural language and the lead figures out how to decompose it. But it also means every coordination decision (who works on what, when a task is done, what happens when something fails) depends on the model getting it right.

Structured workflow orchestration takes the opposite approach. You define the coordination explicitly: which agents run, in what order, with what validation between steps. The model handles execution within each step, but the structure between steps is fixed.

Take the multi-perspective code review from section 2 (security audit, performance review, architectural assessment in parallel) and add a sequential phase: after the reviews complete, an agent synthesizes findings into an action plan, and a final approval step validates the plan before it's marked complete.

This is how we’d set this up with Reliant:

On rejection: Step 2 re-runs with feedback included in context

On approval: workflow completes, action plan delivered

Each agent runs a different model at a different effort level. The Security and Architecture Reviewers run on Opus because those assessments benefit from stronger reasoning. Performance Reviewer runs on Sonnet because it's mostly checking quantitative patterns (N+1 queries, unindexed lookups, unnecessary allocations) where Sonnet is adequate and cheaper. Synthesis Agent runs Opus at max effort because it's doing the hardest reasoning in the workflow: reconciling three perspectives into one coherent plan. Approval Agent runs Sonnet at medium effort because it's checking against known conventions, not generating novel analysis.

In agent teams, all of these would run the same model at the same effort level. For a workflow like this, that means either overpaying for the performance review and approval check (if you run Opus) or under-powering the security review and synthesis (if you run Sonnet).

This matters more because models tend to perform differently across roles. Engineers consistently report that LLMs catch problems during review that they introduced during implementation: the same model that writes a bug will flag it when asked to review against the original spec. If review is where models are most reliable, you want your review agents running at high effort on a strong model, and you can afford to run implementation agents cheaper. Uniform model selection across a team prevents that optimization entirely.

The checkpoint at Step 3 does something agent teams can't express: it gates progress on validation. The approval agent checks the synthesis against the repo's conventions (pulled from local context that smart onboarding generated from the codebase). If the action plan misses something or contradicts a convention, the workflow loops back to Step 2 with specific feedback rather than delivering a flawed result. The team lead in agent teams would need to catch this by reading the output and manually intervening.

And because each step in the workflow is a defined node, execution tracking shows you exactly where things stand: which parallel reviews have completed, whether the synthesis is running, whether the approval passed or rejected. If the workflow fails at Step 2 (say, a rate limit or context overflow), you resume from Step 2 with the Step 1 results still intact rather than re-running the entire pipeline.

Where this doesn't make sense

Structured workflows require you to know the structure upfront. If you're investigating a bug and you don't know whether the problem is in the frontend, the backend, or the database layer, defining a fixed agent sequence before you've explored the problem is premature. Agent teams are better here because the lead can decompose the work dynamically based on what teammates discover.

The same applies to open-ended research, prototyping, and any task where the right decomposition only becomes clear mid-execution. Agent teams trade structural guarantees for flexibility, and that's the right tradeoff when the task is genuinely exploratory.

There's also a subtler limitation: structured workflows shift the bottleneck from "monitoring agent work" to "defining agent work well enough upfront."

Writing a good workflow definition is its own skill. If your task decomposition is wrong, the structure doesn't save you; it just makes you wrong in a more organized way. The workflow builder helps by making decomposition visible and editable, but the thinking still has to come from the engineer.

The decision framework is straightforward: if you can write down the steps before starting, structured orchestration gives you per-agent model selection, checkpoints, visual tracking, and resume capability. If you can't write down the steps because you need to discover them, agent teams let you describe the goal in natural language while the lead figures out decomposition on the fly.

Most real engineering work involves both. You investigate (exploratory, agent teams are well-suited) and then you execute a known process (structured, workflow orchestration is well-suited). A bug goes through an open-ended investigation phase where you don't know what you're looking for, followed by a reproduce-debug-fix-test sequence that follows the same steps every time.

Building on these primitives

Agent teams don't exist in isolation. They combine with Claude Code's other primitives, and the combinations matter more than any single feature.

Custom agents define the roles your teammates play. A teammate spawned as your security-reviewer custom agent carries that agent's system prompt, tool permissions, and behavioral constraints into its isolated session. Skills (CLAUDE.md files) give every agent access to your codebase conventions, API patterns, and architectural decisions. Hooks trigger actions at specific points in the execution: run linting after every file edit, execute tests after implementation, post a summary to Slack when a team completes its work. Together, these primitives turn a generic "investigate this codebase" team into a specific, configured squad that knows your project's rules and follows your team's process.

These combinations are assembled manually. You write the custom agent definitions, maintain the skill files, configure the hooks, and prompt the team lead with the right decomposition strategy. The orchestration layer (who runs when, what validates what, when to stop and check) lives in your prompt and the model's judgment rather than in explicit structure.

Agent teams are still marked experimental in Claude Code's documentation. Anthropic is iterating on the messaging protocol, the coordination patterns, and the interfaces between lead and teammates. The primitives will get more composable, the coordination will get more structured, and the boundary between "flexible agent team" and "defined workflow" will narrow. Future versions will likely support typed message schemas between agents, coordination strategies beyond the lead-teammate pattern, and hook integration for checkpoint-like validation.

For now, the decision framework from section 4 holds. Use agent teams when you need parallel exploration and the decomposition isn't known upfront. Use structured workflows when you need sequential handoffs, per-agent configuration, validation between steps, and organizational reuse. Use both when a task has an exploratory phase followed by a known execution process.

The engineers getting the most out of multi-agent AI right now are the ones who recognize which phase of work they're in and reach for the right primitive. Agent teams gave Claude Code a real parallelism capability. Understanding its boundaries, and knowing what sits beyond them, is how you use it well.