#Claude Code Teams

cmux claude-teams launches Claude Code with agent teams enabled. When Claude spawns teammate agents, they appear as native cmux splits instead of tmux panes, with full sidebar metadata and notifications.

#Usage

cmux claude-teams
cmux claude-teams --continue
cmux claude-teams --model sonnet

All arguments after claude-teams are forwarded to Claude Code. The command defaults teammate mode to auto and sets the environment so Claude uses cmux splits.

#How it works

cmux claude-teams creates a tmux shim script and configures the environment so Claude Code thinks it's running inside tmux. When Claude issues tmux commands to manage teammate panes, the shim translates them into cmux socket API calls.

Creates a tmux shim in the current surface's temporary shim directory. Its path includes the surface UUID and changes per panel and per boot, so no fixed path can be quoted
Sets TMUX and TMUX_PANE to simulate tmux for the Claude Teams launch session
Prepends the shim directory to PATH so Claude finds the shim before real tmux
Enables CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and sets teammate mode to auto

The shim routes to cmux only when CMUX_CLAUDE_TEAMS_CMUX_BIN is set; otherwise it transparently falls through to the next real tmux executable. As a result, which tmux does not tell you whether Claude Teams interception is active.

#Environment variables

Variable	Purpose
`TMUX`	Synthetic tmux socket path for the session that ran cmux claude-teams
`TMUX_PANE`	Synthetic tmux pane identifier for the session that ran cmux claude-teams; empty in spawned agent panels
`CMUX_SURFACE_ID`	The current surface's UUID; use this as the surface identifier inside a spawned agent panel
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`	Enables Claude Code agent teams feature
`CMUX_SOCKET_PATH`	Path to the cmux control socket for the shim to connect to

The synthetic TMUX, TMUX_PANE, and related tmux-compat values describe the session that ran cmux claude-teams, not the spawned panels. From an agent panel, use CMUX_SURFACE_ID and cmux tree --json; the output's caller object identifies the invoking panel.

#Directories

Path	Purpose
Per-surface directory under the system temporary directory (no fixed path)	Contains the active tmux shim and is prepended to PATH for that surface
`~/.cmuxterm/tmux-compat-store.json`	Persistent storage for tmux-compat buffers, hooks, and split placement/layout state

The split-routing keys are:

lastSplitSurface — Maps each workspace UUID to the surface UUID created by the latest split. It seeds the agent-column anchor used to decide where the next main-vertical split lands.
mainVerticalLayouts — Maps each workspace UUID to mainSurfaceId (the main or leader surface) and lastColumnSurfaceId (the bottom-most surface in the agent column). Subsequent teammate splits target that column and stack downward.

These are the routing keys to inspect when a teammate panel appears as a tab behind an existing surface instead of as a split beside it.

#Supported tmux commands

The shim translates these tmux commands into cmux operations:

new-session, new-window → creates a new cmux workspace
split-window → splits the current cmux pane
send-keys → sends text to a cmux surface
capture-pane → reads terminal text from a cmux surface
select-pane, select-window → focuses a cmux pane or workspace
kill-pane, kill-window → closes a cmux surface or workspace
list-panes, list-windows → lists cmux panes or workspaces