#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.

在当前 surface 的临时 shim 目录中创建 tmux shim。路径包含 surface UUID，并且会随面板和每次启动而变化，因此无法给出固定路径
设置 TMUX 和 TMUX_PANE，以便在 Claude Teams 启动会话中模拟 tmux
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

仅当设置了 CMUX_CLAUDE_TEAMS_CMUX_BIN 时，shim 才将请求路由到 cmux；未设置时会透明地继续调用下一个真正的 tmux 可执行文件。因此，which tmux 无法告诉你 Claude Teams 的拦截是否处于活动状态。

#Environment variables

Variable	Purpose
`TMUX`	运行 cmux claude-teams 的会话所使用的合成 tmux socket 路径
`TMUX_PANE`	运行 cmux claude-teams 的会话所使用的合成 tmux pane 标识符；在生成的 agent 面板中为空
`CMUX_SURFACE_ID`	当前 surface 的 UUID；在生成的 agent 面板中将它用作 surface 标识符
`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

合成的 TMUX、TMUX_PANE 及相关 tmux 兼容值描述的是运行 cmux claude-teams 的会话，而不是生成的面板。在 agent 面板中，请使用 CMUX_SURFACE_ID 并运行 cmux tree --json；输出中的 caller 对象会标识调用面板。

#Directories

Path	Purpose
系统临时目录下每个 surface 各自的目录（无固定路径）	包含当前有效的 tmux shim，并针对该 surface 添加到 PATH 最前面
`~/.cmuxterm/tmux-compat-store.json`	用于持久保存 tmux-compat 缓冲区、钩子以及分屏位置/布局状态

分屏路由键包括：

lastSplitSurface — 将每个工作区 UUID 映射到最近一次分屏创建的 surface UUID。它为 agent 列锚点提供初始值，用于决定下一个 main-vertical 分屏的落点。
mainVerticalLayouts — 将每个工作区 UUID 映射到 mainSurfaceId（主 surface 或 leader surface）和 lastColumnSurfaceId（agent 列最底部的 surface）。后续队友分屏会定位到该列并向下堆叠。

如果队友面板出现在现有 surface 后方的标签页中，而不是旁边的分屏中，请检查这些路由键。

#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