When One AI Isn't Enough: Claude Code Agent Teams

Single-agent workflows hit a ceiling faster than most people expect.

Not because the model isn't capable. Because complex problems have multiple fronts, and a single context window can only hold so much before it starts losing the thread. You ask one agent to debug a cross-layer issue spanning frontend, backend, and infrastructure, and by the time it finishes investigating the third layer, it has forgotten what it learned about the first.

Claude Code's experimental Agent Teams feature addresses this directly. Instead of one agent doing everything sequentially, you spin up multiple Claude Code instances that work in parallel, each with its own context window, its own focus area, and the ability to communicate with each other.

This isn't a replacement for single-agent work. Most tasks don't need it. But for the subset of problems that are genuinely parallelizable and complex enough to benefit from multiple independent perspectives, Agent Teams changes how the work gets done.

The Architecture of Coordination

Agent Teams introduces a team lead and teammate model. One Claude Code instance acts as the orchestrator. The rest are teammates, each a full Claude Code instance with independent context.

The distinction from subagents matters.

Three mechanisms hold the system together.

Shared Task List. Every agent sees the same task board. Tasks move through three states: pending, in-progress, and completed. Teammates self-claim pending tasks. The lead can assign them. Anyone can see what's happening across the team.

Mailbox System. Teammates communicate directly with each other, not routed through the lead. If one teammate discovers something relevant to another's work, it sends a message. This matters because peer-to-peer communication avoids the bottleneck of everything flowing through a single orchestrator.

Context Isolation. Each teammate gets a fresh context window. They receive the project's CLAUDE.md, MCP server configurations, available skills, and a spawn prompt from the lead. They do not get the lead's conversation history. This is intentional—it prevents context pollution and lets each teammate focus on its specific assignment without inheriting assumptions from earlier in the lead's session.

When Agent Teams Make Sense (And When They Don't)

The overhead of spinning up multiple agents is real. Each teammate consumes tokens independently. Coordination takes effort. If your task is fundamentally sequential or simple, Agent Teams adds cost without benefit.

Here's where it earns its keep.

Parallel research across multiple codebases. You need to understand how three different services handle authentication. Instead of one agent switching between repos and losing context, three teammates each dive into one service and report back.

Competing hypotheses during debugging. Say users report the app exits after one message. You suspect it could be a WebSocket disconnect, a state management bug, a race condition in the message handler, a configuration issue, or a frontend rendering crash. Spawn five teammates, one per hypothesis. Each investigates independently, and critically, they can disprove each other's findings through the mailbox system.

Cross-layer coordination. Frontend, backend, and infrastructure changes that need to happen together but can be developed in parallel. Each teammate works on its layer and communicates interface contracts with the others.

Multi-perspective code review. One teammate checks security, another checks performance, a third validates test coverage. Each brings a focused lens instead of one reviewer trying to hold everything in mind.

The anti-patterns are equally clear.

Sequential tasks where step two depends on step one's output don't benefit from parallelization. Same-file edits create merge conflicts between teammates. Simple tasks that a single agent handles in minutes don't justify the coordination overhead. If you're fixing a typo, you don't need a team.

Control Patterns and Communication

Three control patterns shape how teams operate.

Delegate Mode is activated with Shift+Tab. It restricts the lead to coordination-only tools. The lead cannot write code, edit files, or run commands. It can only spawn teammates, assign tasks, and review work. This forces a clean separation between orchestration and execution. If you want the lead to think strategically instead of getting pulled into implementation details, delegate mode enforces that discipline.

Plan Approval puts a checkpoint into the flow. A teammate works in read-only mode, analyzing the problem and producing a plan. That plan gets sent to the lead for review. The lead approves, rejects, or modifies it before the teammate proceeds with implementation. This is useful when you want to verify the approach before committing tokens to execution.

Direct Messaging lets you target communication. Message one specific teammate, or broadcast to all. Combined with the mailbox system, this creates a communication structure that mirrors how effective human teams actually work: some messages are one-on-one, others are announcements.

For navigation, Shift+Up/Down cycles between teammates in in-process mode (single terminal). In split-pane mode (tmux), you click the pane you want. Ctrl+T toggles the task list view so you can see the current state of all work across the team.

Task dependencies are supported. You can specify that Task B shouldn't start until Task A completes. File locking prevents two teammates from editing the same file simultaneously. These are the kind of coordination primitives you'd expect in any distributed system.

Getting Started

Agent Teams is experimental. You enable it by setting an environment variable in your Claude Code settings:

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

Three display modes control how teammates appear.

auto (the default) detects whether you're running inside tmux. If yes, it uses split panes. If not, it uses in-process mode.

in-process keeps everything in a single terminal. Teammates run within the same window and you navigate between them with keyboard shortcuts.

tmux gives each teammate its own pane in a split layout. This requires tmux or iTerm2. It's the clearest visual representation of what's happening but not supported everywhere.

Starting a team is natural language. You describe what you want, and the lead figures out how to decompose it:

Design a CLI tool for managing configuration files. Spawn teammates for:
1. UX research — investigate existing CLI tools for patterns and conventions
2. Architecture — design the module structure and data flow
3. Devil's advocate — challenge every design decision and find edge cases

The lead spawns three teammates, each with a focused prompt and access to the same project context. They work in parallel, and the devil's advocate actively pushes back on what the other two propose.

That's the part worth highlighting. Teammates aren't just parallel workers. They can be assigned adversarial roles. One builds while another stress-tests. One proposes while another critiques. This kind of structured disagreement is hard to get from a single agent.

Limitations Worth Knowing

Experimental means experimental. Some of these will get fixed. Some are architectural constraints. Worth knowing either way.

• No session resumption for in-process teammates. If you close the terminal, teammate state is lost. The lead persists, but teammates need to be re-spawned.
• Task status can lag. Teammates may finish work before the task list reflects it. You might need to manually update task states.
• One team per session. You cannot run multiple independent teams from a single Claude Code session.
• No nested teams. Teammates cannot spawn their own teams. The hierarchy is flat by design.
• Fixed leadership. You cannot promote a teammate to lead or transfer leadership mid-session.
• Permissions are set at spawn time and apply uniformly to all teammates. You cannot give different teammates different permission levels.
• Split panes don't work everywhere. VS Code's integrated terminal, Windows Terminal, and Ghostty lack support. Use a standalone terminal with tmux or iTerm2.
• Shutdown is slow. Teammates finish their current request before stopping. If a teammate is mid-task, you wait.
• Always clean up through the lead. Don't try to terminate teammates directly.

These are the kind of rough edges you expect from an experimental feature. None of them are dealbreakers, but they shape how you use the system.

Practical Tips

After spending time with Agent Teams, some patterns emerge.

Give teammates rich spawn prompts. They don't inherit the lead's conversation history. Include specific file paths, technology stack details, and the exact question you want them to answer. Vague prompts produce vague work.

Size tasks appropriately. Five to six tasks per teammate is the sweet spot. Fewer and you're underutilizing the parallelism. More and the teammate's context window starts to strain.

Wait before synthesizing. Let teammates finish their work before asking the lead to pull everything together. If you ask the lead to synthesize while teammates are still working, you get incomplete conclusions.

Start with research and review. These are the safest tasks for Agent Teams because they're inherently parallelizable and don't involve conflicting file edits. Once you're comfortable with the coordination patterns, move to implementation tasks.

Assign different file sets. If two teammates need to write code, make sure they're working on different files. File locking helps, but avoiding conflicts in the first place is better.

Don't let teams run unattended for too long. Monitor progress and steer when needed. The system is good but not infallible. A teammate can go down a rabbit hole that wastes tokens without producing value.

Pre-approve common operations. Permission prompts interrupt flow. If you know your teammates will need to read files and run tests, approve those operations at spawn time to reduce interruptions.

Where This Points

Agent Teams is a distributed systems problem applied to AI workflows.

Task lists, mailboxes, context isolation, file locking, leader election (fixed, for now). These are coordination primitives borrowed from decades of distributed computing. The fact that they're being applied to AI agents isn't surprising. It was inevitable once single-agent context windows became the bottleneck.

The rough edges are real. Session resumption, task status lag, fixed permissions. These will improve. The architecture is what matters, and the architecture points toward a future where AI-assisted development looks less like a single conversation and more like managing a team.

Whether that's the right direction depends on the task. Most coding work doesn't need multiple agents. A focused single agent with good context handles the majority of real-world development tasks effectively.

But for the problems that are genuinely complex, genuinely parallelizable, and genuinely benefit from multiple perspectives — debugging a production incident across three services, reviewing a codebase from security and performance angles simultaneously, exploring competing architectural approaches — Agent Teams offers something a single agent cannot: the ability to hold multiple independent trains of thought at the same time.

Try it on one research-heavy task. See if the parallelization justifies the overhead. That's the only way to know if it fits your workflow.

Source: Claude Code Agent Teams Documentation