Skip to main content

​
What Are Agent Teams?

Agent Teams enable multiple Claude instances to collaborate on shared tasks, with one session acting as the lead coordinator and spawning teammates to work in parallel. This is an experimental feature built into Claude Code that AI Runner exposes through the --team flag. Key characteristics:
  • One lead agent coordinates the work
  • Teammates are spawned as needed for parallel execution
  • Coordination uses Claude Code’s internal task list and mailbox (not provider-specific)
  • Works with all providers — AWS, Vertex, Ollama, Vercel, etc.
  • Interactive mode only — not supported in shebang/piped script modes

​
Quick Start

​
How It Works

Agent Teams leverage Claude Code’s internal coordination system:
  1. Lead Agent: The main session you interact with
  2. Task List: Shared work queue managed by the lead
  3. Mailbox: Inter-agent communication channel
  4. Teammates: Spawned workers that execute tasks and report back
The lead agent breaks down complex tasks, delegates work to teammates, and synthesizes results. All coordination happens through Claude Code’s internal mechanisms — there’s no provider-specific orchestration.

​
Flags and Options

​
--team Flag

AI Runner flag that enables agent teams by setting the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable.

​
--teammate-mode Flag

Claude Code native flag (passed through by AI Runner) that controls how teammates are displayed:
Note: --teammate-mode without --team has no effect (teammates aren’t spawned).

​
Limitations

​
Interactive Mode Only

Agent teams require an interactive session. Scripts (shebang/piped) run in single-agent mode:
If you specify --team in a script, AI Runner shows a warning and disables it:

​
Token Scaling

Each teammate consumes tokens independently. Token usage scales roughly linearly with the number of active teammates:
  • 1 teammate active: ~1× normal token usage
  • 3 teammates active: ~3× normal token usage
  • 5 teammates active: ~5× normal token usage
The lead agent coordinates work to minimize redundant operations, but parallel execution inherently uses more tokens than sequential work. Cost implications:
  • More teammates = faster completion but higher cost
  • The lead agent spawns teammates as needed (not all at once)
  • Simple tasks may not spawn teammates at all

​
Provider Compatibility

Agent teams work with all providers because coordination is internal to Claude Code:
The provider’s API sees individual requests from each agent (lead + teammates). From the provider’s perspective, it’s just multiple concurrent sessions.

​
Use Cases

​
Parallel File Operations

Refactoring, migration, or analysis across multiple files:
Teammates work on different files simultaneously while the lead ensures consistency.

​
Complex Multi-Step Tasks

Tasks with independent subtasks:
Each teammate handles one aspect while the lead coordinates.

​
Large Codebase Analysis

Investigating patterns across many files:
Teammates scan different modules in parallel.

​
Saving Team Mode as Default

Use --set-default to persist your team configuration:

​
Troubleshooting

​
Teams Not Spawning

If you enable --team but don’t see teammates:
  1. Check mode: Teams only work in interactive sessions, not scripts
  2. Task complexity: Simple tasks may not need teammates
  3. Environment: Run ai-status to verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set

​
Tmux Mode Not Working

If --teammate-mode tmux doesn’t split panes:
  1. Tmux installed: which tmux should return a path
  2. Inside tmux: The flag only works when already in a tmux session
  3. Fallback: Claude Code falls back to in-process if tmux unavailable

​
High Token Usage

If you’re seeing unexpectedly high token consumption:
  1. Multiple teammates: Check how many teammates are active (scales linearly)
  2. Use smaller model for teammates: Override the small/fast model in ~/.ai-runner/secrets.sh:
  3. Disable teams: Remove --team if parallel execution isn’t needed