#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

shim 只有在設定了 CMUX_CLAUDE_TEAMS_CMUX_BIN 時才會將請求路由至 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 緩衝區、hook，以及分割位置/版面配置狀態

分割路由鍵包括：

lastSplitSurface — 將每個工作區 UUID 對應到最近一次分割所建立的 surface UUID。它會初始化 agent 欄錨點，用來決定下一個 main-vertical 分割的落點。
mainVerticalLayouts — 將每個工作區 UUID 對應到 mainSurfaceId（主要或 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