How to run a Claude Code agent team with an Opus lead and Haiku teammates (--teammate-mode only sets the display)

A post on X claimed that turning on CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and launching claude --model opus --teammate-mode auto gives you an Opus lead with a swarm of Haiku teammates. The environment variable is right. --teammate-mode has nothing to do with teammate models: it only decides whether teammates run inside your terminal (in-process) or in tmux or iTerm2 split panes.

1. Turn on agent teams. The feature is experimental and off by default.

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

1. Start the lead session on Opus.

claude --model opus

1. Name the teammate model in the prompt that asks for the team.

Spawn 3 teammates to cover security, performance and tests. Run every teammate on Haiku.

Claude Code picks a teammate's model in this order: the model your prompt names, then the model of the subagent definition the teammate was spawned from, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the lead's model. If you'd rather not repeat it, set CLAUDE_CODE_SUBAGENT_MODEL=haiku, but note it applies to ordinary subagents too. The old teammateDefaultModel setting was removed in v2.1.234 and is ignored if left in place.

Use --teammate-mode auto (or "teammateMode": "auto" in settings) only when you want split panes. Inside tmux, or in iTerm2 with the it2 CLI installed, teammates get their own panes; otherwise they run in-process. Each teammate is a separate Claude instance, so a team uses far more tokens than a single session.