Claude Code agent teams

Claude Code agent teams let one Claude Code session lead several teammate sessions that share a task list and message each other. Inside tmux, Claude Code can open each teammate in its own split pane. tmux-ide shows those panes with the teammate's name, its team and live working, blocked, done or idle status. Claude Code runs the team; tmux-ide shows it.

What Claude Code agent teams are

An agent team is a Claude Code lead plus teammates, each a full Claude Code session with its own context. The lead assigns work through a shared task list, and teammates message each other directly. Agent teams are experimental in Claude Code and off by default. Anthropic's agent teams guide covers how to prompt and manage a team.

Turn on agent teams in tmux

Add two keys to ~/.claude/settings.json:

{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
  "teammateMode": "auto"
}

teammateMode decides where teammates appear:

tmux-ide works with teammates in tmux split panes, so use "auto" or "tmux" and run Claude Code inside a tmux-ide session.

Start a team in a tmux-ide session

For exact status, install the Claude Code hooks once:

tmux-ide integration install claude

Then start claude in any tmux-ide session and ask it for teammates, for example "Spawn three teammates to review this PR: one for security, one for performance, one for tests." Claude Code opens each teammate in its own pane. Hooks are read when a session starts, so restart Claude Code sessions that were running before you installed them.

What tmux-ide shows

tmux-ide reads Claude Code's runtime team file, ~/.claude/teams/<team>/config.json, about every two seconds and never writes it. A pane gets a teammate's name only when both of these hold:

• the file lists that member with a tmux backend and this pane;
• the live claude process in the pane carries the matching team, agent id and agent name.

Anything else, such as a removed or unrecognized file, an iTerm2 backend or an ambiguous match, falls back to ordinary pane naming. Each machine's daemon reads that machine's files.

Work with teammates from outside the team

Teammate panes are ordinary tmux panes, so tmux-ide's commands work on them:

tmux-ide agent explain %4                                  # how the teammate's state was decided
tmux-ide wait output %4 --match "tests passed"             # wait for a teammate's output
tmux-ide wait agent-status review --status done            # wait for the whole session
tmux-ide send %4 "Also check the upload limit"             # type into the teammate's prompt

tmux-ide send types into the pane, like clicking into it and typing. It is not a team message: it doesn't go through Claude Code's mailbox, and the lead doesn't see it. For attributed, retry-safe sends, use agent automation.

Set it up automatically

Needs a release newer than 2.9.3. The tmux-ide installer adds the two settings.json keys for you when Claude Code is installed. It adds each key only if it is missing, keeps a backup, never rewrites a file that isn't valid JSON, and never overrides a value you already set, including an explicit "0". To skip it, pass --no-claude-agent-teams to install.sh or set TMUX_IDE_NO_CLAUDE_AGENT_TEAMS=1.

The same release adds a command to check or change the setting:

tmux-ide integration agent-teams status
tmux-ide integration agent-teams disable   # writes "0"; future installs respect it
tmux-ide integration agent-teams enable    # turns it back on, even after a "0"

What tmux-ide does not do

Claude Code owns the team: creating it, spawning and shutting down teammates, the shared task list and the mailbox. tmux-ide never writes Claude's team files and does not route messages through the mailbox.

• In-process teammates live inside the lead's terminal and have no panes, so tmux-ide does not show them separately.
• The lead is not tagged automatically, because it is not listed with a tmux pane. Group it with tmux-ide team assign %PANE "<team>"; a manual assignment takes precedence over discovered grouping.
• tmux-ide send is not a team message, and the lead does not see it.
• Restore rebuilds the panes but not the team. Claude Code removes the team file when the lead session ends, so grouping disappears too. With --resume-agents, a teammate pane that recorded a session id comes back as an ordinary claude --resume conversation, not as a member of the team.
• New agent… in the app starts an independent session; it does not add a teammate to Claude's team.

Common questions

Do I need tmux for Claude Code agent teams?

No. By default, teammates run in-process inside the lead's terminal. Split panes need tmux, or iTerm2 with its it2 CLI according to Anthropic's guide. tmux-ide recognizes teammates only in tmux panes.

Does tmux-ide orchestrate the team?

No. Claude Code's lead, task list and mailbox do. tmux-ide shows the teammate panes, their names and their status.

Why isn't the lead grouped with its teammates?

Claude Code doesn't list the lead with a tmux pane, so tmux-ide can't match it. Group it yourself:

tmux-ide team assign %1 "<team>"

Can I add Codex or other agents to a Claude team?

Not to Claude Code's team; its teammates are Claude Code sessions. You can group any pane, including Codex, into a tmux-ide team with tmux-ide team assign and coordinate it with send and wait. See Multi-agent teams.

Does tmux-ide restore bring the team back?

It brings back the panes and, with --resume-agents, their conversations, but as ordinary Claude Code sessions, not as members of a team. Ask the lead to spawn new teammates.

See also

• Multi-agent teams — coordinate mixed agents with send and wait
• Agent detection — how each teammate's status is decided
• Restore and resume — what comes back after a crash
• Agent automation — attributed reads and sends
• Anthropic's agent teams guide — prompting and managing a team