Back to Details

cmux

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cmux Control

cmux 控制

cmux is a native macOS terminal app for running multiple AI coding agents in parallel. It exposes a CLI (
cmux
) and a Unix-socket JSON-RPC API (
/tmp/cmux.sock
) for full topology and browser control.
cmux是一款原生macOS终端应用，可并行运行多个AI编码代理。它提供CLI（
cmux
）和Unix套接字JSON-RPC API（
/tmp/cmux.sock
），用于全面控制拓扑结构与浏览器。

Core Concepts

核心概念

  • Window — top-level macOS cmux window
  • Workspace — sidebar tab within a window (one git branch / project context)
  • Pane — split region inside a workspace
  • Surface — tab inside a pane (terminal or browser)
Handles default to short refs (
workspace:2
, 
pane:1
, 
surface:7
); UUIDs accepted as input. Add 
--id-format uuids|both
for UUID output.
  • Window — 顶级macOS cmux窗口
  • Workspace — 窗口内的侧边栏标签（对应一个Git分支/项目上下文）
  • Pane — 工作区内的拆分区域
  • Surface — 窗格内的标签页（终端或浏览器）
句柄默认使用短引用（如
workspace:2
、
pane:1
、
surface:7
）；也支持UUID作为输入。添加
--id-format uuids|both
参数可输出UUID。

Ref syntax — get this right or fail silently

引用语法 — 必须正确使用，否则会静默失败

  • Always use PREFIXED refs (
    pane:38
    , 
    surface:46
    ). A bare number is treated as an INDEX, not an ID — 
    --surface 46
    means "the surface at index 46" (usually nonexistent → silent failure), NOT 
    surface:46
    .
  • read-screen
    and 
    capture-pane
    have NO 
    --pane
    flag     — they target 
    --workspace
    or 
    --surface
    only. Passing 
    --pane
    errors, and a bare/missing target falls back to your OWN surface (you'll read your own footer and draw wrong conclusions). To read a pane: resolve it to a surface FIRST with 
    cmux list-pane-surfaces --pane pane:N
    , then 
    cmux read-screen --surface surface:N
    .
  • Never append 
    2>/dev/null
    to cmux commands.     Errors go to stderr with exit code 1; suppressing them blinds you to your own ref/flag mistakes (the #1 cause of "(no output)").
  • 始终使用带前缀的引用（如
    pane:38
    、
    surface:46
    ）。纯数字会被视为索引，而非ID——
    --surface 46
    表示“索引为46的界面”（通常不存在→静默失败），而非
    surface:46
    。
  • read-screen
    和
    capture-pane
    命令没有
    --pane
    参数    ——它们仅针对
    --workspace
    或
    --surface
    。传入
    --pane
    会报错，若未指定目标或使用纯数字，会默认指向你自己的界面（你会读取到自己的页脚，进而得出错误结论）。要读取窗格内容：需先通过
    cmux list-pane-surfaces --pane pane:N
    将其解析为界面，再执行
    cmux read-screen --surface surface:N
    。
  • 切勿在cmux命令后追加
    2>/dev/null
    。错误信息会输出到stderr并返回退出码1；抑制错误会让你无法发现引用/参数错误（这是“无输出”问题的头号原因）。

Detect cmux in a Shell

在Shell中检测cmux环境

bash
[ -S "${CMUX_SOCKET_PATH:-/tmp/cmux.sock}" ] || exit 0   # bail if not in cmux
[ -n "${CMUX_WORKSPACE_ID:-}" ] && echo "inside cmux surface"
Injected env vars in every cmux-spawned terminal: 
CMUX_WORKSPACE_ID
, 
CMUX_SURFACE_ID
, 
CMUX_SOCKET_PATH
, 
CMUX_PORT
. Always anchor automation to 
CMUX_WORKSPACE_ID
 — the visually focused workspace may not be the agent's caller workspace.
bash
[ -S "${CMUX_SOCKET_PATH:-/tmp/cmux.sock}" ] || exit 0   # 若不在cmux环境中则退出
[ -n "${CMUX_WORKSPACE_ID:-}" ] && echo "inside cmux surface"
每个由cmux启动的终端都会注入环境变量：
CMUX_WORKSPACE_ID
、
CMUX_SURFACE_ID
、
CMUX_SOCKET_PATH
、
CMUX_PORT
。自动化操作始终以
CMUX_WORKSPACE_ID
为锚点——视觉上聚焦的工作区不一定是代理调用者所在的工作区。

Fast Start — Topology

快速入门 — 拓扑结构管理

bash
cmux identify --json                              # who am I (window/workspace/pane/surface)
cmux tree                                         # full hierarchy
cmux list-workspaces --json
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-surfaces --workspace "$CMUX_WORKSPACE_ID"

cmux new-workspace --name "feature-x" --cwd /path/to/repo
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type browser  --direction right --url http://localhost:3000
cmux move-surface --surface surface:7 --pane pane:2 --focus false
cmux split-off --surface surface:7 right
cmux reorder-surface --surface surface:7 --before surface:3
cmux close-surface --surface surface:7
bash
cmux identify --json                              # 识别当前身份（窗口/工作区/窗格/界面）
cmux tree                                         # 查看完整层级结构
cmux list-workspaces --json
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-surfaces --workspace "$CMUX_WORKSPACE_ID"

cmux new-workspace --name "feature-x" --cwd /path/to/repo
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type browser  --direction right --url http://localhost:3000
cmux move-surface --surface surface:7 --pane pane:2 --focus false
cmux split-off --surface surface:7 right
cmux reorder-surface --surface surface:7 --before surface:3
cmux close-surface --surface surface:7

Polling Pi Agents in Panes — Keep Sleeps Short

轮询窗格中的Pi代理 — 缩短休眠间隔

When launching a Pi Agent inside a cmux pane and polling for output, use short 
sleep
intervals (2–5s). Pi is fast and minimal, and David runs it on Opus 4.8 Fast via OpenRouter, which streams tokens extremely quickly. Do NOT use 
sleep 15
unless genuinely needed (a big build/refactor) — most of the time 
sleep 2
–
sleep 5
is more than enough.
After every agent check, send the user a one-line status update: what the agent is doing and whether it is on track. Keep it extremely concise.
Claude Code cmux note: after Claude finishes, it may prefill a predicted next user message; that draft is Claude, not the user speaking.
当在cmux窗格中启动Pi代理并轮询输出时，请使用短休眠间隔（2–5秒）。Pi运行速度快且轻量化，David通过OpenRouter在Opus 4.8 Fast上运行它，令牌流速度极快。除非确实需要（如大型构建/重构），否则请勿使用
sleep 15
——大多数情况下
sleep 2
至
sleep 5
就足够了。
每次检查代理状态后，向用户发送一行状态更新：说明代理正在执行的操作以及是否按计划进行。内容需极其简洁。
Claude Code cmux注意事项：Claude完成任务后，可能会预填充预测的下一条用户消息；该草稿是Claude生成的，并非用户的真实输入。

Send Input

发送输入

Command names: there is NO 
send-surface
/ 
send-key-surface
. Target a specific surface with the 
--surface
flag on 
send
/ 
send-key
(same commands as the focused terminal). 
send-panel
/ 
send-key-panel
exist ONLY for panels (
--panel
), not surfaces.
bash
cmux send "echo hi\n"                                       # focused terminal
cmux send-key "ctrl+c"                                       # enter|tab|esc|backspace|arrows|ctrl+x|shift+tab
cmux send --surface surface:7 "npm run build"               # specific surface (NOT send-surface)
cmux send-key --surface surface:7 enter                     # specific surface (NOT send-key-surface)
命令名称说明：不存在
send-surface
/
send-key-surface
命令。需在
send
/
send-key
命令上使用
--surface
参数指定目标界面（与聚焦终端使用相同命令）。
send-panel
/
send-key-panel
仅适用于面板（需搭配
--panel
参数），不适用于界面。
bash
cmux send "echo hi\n"                                       # 向聚焦终端发送输入
cmux send-key "ctrl+c"                                       # 支持enter|tab|esc|backspace|箭头键|ctrl+x|shift+tab等
cmux send --surface surface:7 "npm run build"               # 向指定界面发送输入（请勿使用send-surface）
cmux send-key --surface surface:7 enter                     # 向指定界面发送按键（请勿使用send-key-surface）

Notifications & Sidebar Metadata

通知与侧边栏元数据

bash
cmux notify --title "Done" --body "tests passed"
cmux set-status build "compiling" --icon hammer --color "#ff9500"
cmux set-progress 0.5 --label "Building..."
cmux log --level success "All 42 tests passed"               # info|progress|success|warning|error
cmux trigger-flash --workspace "$CMUX_WORKSPACE_ID"          # blue-ring attention cue
cmux sidebar-state --json                                    # dump all sidebar metadata
bash
cmux notify --title "Done" --body "tests passed"
cmux set-status build "compiling" --icon hammer --color "#ff9500"
cmux set-progress 0.5 --label "Building..."
cmux log --level success "All 42 tests passed"               # 支持info|progress|success|warning|error级别
cmux trigger-flash --workspace "$CMUX_WORKSPACE_ID"          # 触发蓝色环形提示，吸引注意力
cmux sidebar-state --json                                    # 导出所有侧边栏元数据

Browser Automation (WKWebView)

浏览器自动化（WKWebView）

Workflow: open → wait → snapshot → act → re-snapshot.
bash
S=$(cmux --json browser open https://example.com | jq -r .result.surface_ref)
cmux browser "$S" wait --load-state complete --timeout-ms 15000
cmux browser "$S" snapshot --interactive                     # returns elements as e1, e2, ...
cmux browser "$S" fill e1 "<email-address>"
cmux browser "$S" click e2 --snapshot-after
工作流程：打开 → 等待 → 快照 → 操作 → 重新快照。
bash
S=$(cmux --json browser open https://example.com | jq -r .result.surface_ref)
cmux browser "$S" wait --load-state complete --timeout-ms 15000
cmux browser "$S" snapshot --interactive                     # 返回元素标识e1、e2……
cmux browser "$S" fill e1 "<email-address>"
cmux browser "$S" click e2 --snapshot-after

Navigation / inspection

导航/检查

cmux browser "$S" goto URL | back | forward | reload cmux browser "$S" get url | get title | get text body | get value "#email" | get count ".row" cmux browser "$S" eval 'return document.title'
cmux browser "$S" goto URL | back | forward | reload cmux browser "$S" get url | get title | get text body | get value "#email" | get count ".row" cmux browser "$S" eval 'return document.title'

Waits

等待操作

cmux browser "$S" wait --selector "#ready" --timeout-ms 10000 cmux browser "$S" wait --url-contains "/dashboard" --timeout-ms 10000
cmux browser "$S" wait --selector "#ready" --timeout-ms 10000 cmux browser "$S" wait --url-contains "/dashboard" --timeout-ms 10000

Session

会话管理

cmux browser "$S" cookies get | cookies set --name foo --value bar cmux browser "$S" state save /tmp/auth.json | state load /tmp/auth.json
cmux browser "$S" cookies get | cookies set --name foo --value bar cmux browser "$S" state save /tmp/auth.json | state load /tmp/auth.json

Diagnostics

诊断

cmux browser "$S" console list | errors list | screenshot

**Not supported by WKWebView** (return `not_supported`): viewport emulation, geolocation/offline emulation, trace recording, network route interception, raw input injection.
cmux browser "$S" console list | errors list | screenshot

**WKWebView不支持的功能**（会返回`not_supported`）：视口模拟、地理位置/离线模拟、跟踪记录、网络路由拦截、原始输入注入。

Markdown Viewer

Markdown查看器

bash
cmux markdown open plan.md --direction right                 # live-watching renderer
cmux open file.pdf                                           # auto-routes to right viewer
cmux markdown open
flags: 
--workspace
, 
--surface
, 
--window
, 
--direction <right|down|left|up>
, 
--focus <true|false>
. There is NO 
--pane
flag — passing it errors. To target a pane, pass 
--surface <existing-md-surface-in-that-pane>
.
bash
cmux markdown open plan.md --direction right                 # 实时渲染的Markdown查看器
cmux open file.pdf                                           # 自动路由到对应查看器
cmux markdown open
支持的参数：
--workspace
、
--surface
、
--window
、
--direction <right|down|left|up>
、
--focus <true|false>
。不存在
--pane
参数——传入该参数会报错。若要指定窗格，请传入
--surface <该窗格中已存在的markdown界面>
。

Reuse the existing right markdown pane (don't spawn strays)

复用右侧现有Markdown窗格（避免生成多余窗格）

Default behavior of 
markdown open
is to create a new pane every time, even with 
--direction right
. To keep all docs as tabs in ONE right pane, follow this exactly:
bash
undefined
markdown open
的默认行为是每次都创建新窗格，即使使用
--direction right
参数。要让所有文档作为标签页保留在同一个右侧窗格中，请严格遵循以下步骤：
bash
undefined

1. Find the right pane and its surfaces (anchor to THIS workspace)

1. 找到右侧窗格及其界面（锚定到当前工作区）

cmux list-panes --workspace "$CMUX_WORKSPACE_ID" cmux list-pane-surfaces --pane pane:10 # the right/helper pane
cmux list-panes --workspace "$CMUX_WORKSPACE_ID" cmux list-pane-surfaces --pane pane:10 # 右侧/辅助窗格

2. Open targeting an existing markdown surface IN that pane (reuses pane, adds tab)

2. 打开时指定该窗格中已存在的Markdown界面（复用窗格，添加新标签页）

cmux markdown open /abs/path/file.md --surface surface:12 --focus false
cmux markdown open /abs/path/file.md --surface surface:12 --focus false

3. If it STILL spawned a new pane (it can), move the new surface in + verify

3. 如果仍然生成了新窗格（可能发生），移动新界面并验证

cmux move-surface --surface surface:NEW --pane pane:10 --focus false cmux list-panes --workspace "$CMUX_WORKSPACE_ID" # confirm stray pane is gone
undefined
cmux move-surface --surface surface:NEW --pane pane:10 --focus false cmux list-panes --workspace "$CMUX_WORKSPACE_ID" # 确认多余窗格已消失
undefined

Swapping the file in the single right pane (close-FIRST, then open)

替换右侧单个窗格中的文件（先关闭，再打开）

To replace the doc shown in your one right markdown pane, the ONLY reliable order is close the previous surface FIRST, then 
markdown open
the new file fresh — never move an existing viewer, never open-then-close.
bash
undefined
要替换右侧单个Markdown窗格中显示的文档，唯一可靠的顺序是先关闭之前的界面，再重新打开新文件——切勿移动现有查看器，也不要先打开再关闭旧界面。
bash
undefined

1. close the previous right markdown surface (right side goes empty)

1. 关闭之前的右侧Markdown界面（右侧变为空白）

cmux list-panes --workspace "$CMUX_WORKSPACE_ID" cmux close-surface --surface surface:PREV
cmux list-panes --workspace "$CMUX_WORKSPACE_ID" cmux close-surface --surface surface:PREV

2. THEN open the new file fresh

2. 然后重新打开新文件

cmux markdown open /abs/path/new.md --direction right --focus false

ORDER MATTERS: close-previous BEFORE open-new. Opening first then closing the old one, or `move-surface`-ing an existing viewer, leaves the right pane BLANK.
cmux markdown open /abs/path/new.md --direction right --focus false

顺序至关重要：先关闭旧界面，再打开新界面。如果先打开再关闭旧界面，或使用`move-surface`移动现有查看器，右侧窗格会变为空白。

Hard-won lessons (avoid the trial-and-error)

经验教训（避免反复试错）

  • Surface refs are global, not per-workspace. A ref like 
    surface:126
    from an earlier 
    markdown open
    may live in a different window/workspace. Always re-list (
    list-panes
    / 
    list-pane-surfaces
    ) before reusing a ref — never assume a ref from a previous turn is still in the right pane.
  • move-surface
    -ing a markdown viewer often leaves it BLANK.     The moved surface keeps 
    type=markdown
    and 
    surface-health
    looks fine, but renders nothing. Fix: 
    close-surface
    it and 
    cmux markdown open <path>
    fresh, then move the fresh surface if needed. Don't waste time on 
    refresh-surfaces
    — it usually won't fix a moved-then-blank viewer.
  • You cannot screenshot or 
    read-screen
    a markdown surface     (
    Surface is not a terminal
    / browser screenshot is WKWebView-only). To verify a markdown viewer rendered, ask the user or open the file in a browser surface instead. Don't burn turns trying to capture it.
  • cmux list-surfaces
    does not exist.     Use 
    cmux list-pane-surfaces [--pane ...]
    .
  • 界面引用是全局的，而非按工作区划分。之前
    markdown open
    生成的引用如
    surface:126
    可能位于其他窗口/工作区中。复用引用前务必重新列出（
    list-panes
    /
    list-pane-surfaces
    ）——切勿假设之前的引用仍在右侧窗格中。
  • 移动Markdown查看器后常出现空白。移动后的界面仍保留
    type=markdown
    ，且
    surface-health
    显示正常，但无法渲染内容。解决方法：关闭该界面，重新执行
    cmux markdown open <path>
    ，若需要再移动新生成的界面。不要浪费时间尝试
    refresh-surfaces
    ——通常无法修复移动后空白的查看器。
  • 无法对Markdown界面执行截图或
    read-screen
    操作    （提示
    Surface is not a terminal
    / 浏览器截图仅支持WKWebView）。要验证Markdown查看器是否渲染成功，请询问用户或在浏览器界面中打开文件。不要浪费时间尝试捕获内容。
  • 不存在
    cmux list-surfaces
    命令    。请使用
    cmux list-pane-surfaces [--pane ...]
    。

Settings & Config

设置与配置

bash
cmux docs settings        # prints paths, schema URL, reload cmd — read BEFORE editing
cmux settings path        # path to cmux.json
cmux settings cmux-json   # open in editor
cmux reload-config        # hot-reload cmux.json + ~/.config/ghostty/config (Cmd+Shift+,)
Locations:
  • cmux settings: 
    ~/.config/cmux/cmux.json
    (canonical). Project-local override: 
    .cmux/cmux.json
    or 
    ./cmux.json
    .
  • Terminal rendering (font, cursor, theme, scrollback, opacity, blur): 
    ~/.config/ghostty/config
    — NOT cmux.json.
Before editing 
cmux.json
, copy it to a timestamped 
.bak
next to it so the user can revert. Schema: 
https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json
.
bash
cmux docs settings        # 打印路径、Schema URL、重载命令——编辑前务必阅读
cmux settings path        # 查看cmux.json的路径
cmux settings cmux-json   # 在编辑器中打开cmux.json
cmux reload-config        # 热重载cmux.json + ~/.config/ghostty/config（快捷键Cmd+Shift+,）
配置文件位置：
  • cmux设置：
    ~/.config/cmux/cmux.json
    （标准路径）。项目本地覆盖配置：
    .cmux/cmux.json
    或
    ./cmux.json
    。
  • 终端渲染设置（字体、光标、主题、回滚、透明度、模糊）：
    ~/.config/ghostty/config
    ——不在cmux.json中。
编辑
cmux.json
前，请将其复制到同一目录下并添加时间戳后缀作为备份（如
.bak
），以便用户可以恢复。Schema地址：
https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json
。

Sidebar text blurbs under workspaces

工作区下方的侧边栏文本说明

The paragraph under each sidebar workspace title has TWO sources, each with its own toggle in 
cmux.json
(also in Settings > Sidebar):
jsonc
"sidebar": {
  "showWorkspaceDescription": false,  // custom/AI workspace descriptions
  "showNotificationMessage": false    // latest agent message preview (the "Repo scanned…" style blurb)
}
The user keeps BOTH off (set 18-07-2026) — don't re-enable. 
sidebar.hideAllDetails: true
hides the entire detail block (status, branch, cwd) if ever needed.
每个侧边栏工作区标题下方的段落有两个来源，分别在
cmux.json
中有对应的开关（也可在设置>侧边栏中调整）：
jsonc
"sidebar": {
  "showWorkspaceDescription": false,  // 自定义/AI生成的工作区描述
  "showNotificationMessage": false    // 最新代理消息预览（如“仓库已扫描…”样式的说明）
}
用户已将这两个开关关闭（设置时间：2026-07-18）——请勿重新启用。若需要隐藏整个详情块（状态、分支、当前工作目录），可设置
sidebar.hideAllDetails: true
。

Agent Hooks & Install

代理钩子与安装

bash
brew tap manaflow-ai/cmux && brew install --cask cmux
sudo ln -sf /Applications/cmux.app/Contents/Resources/bin/cmux /usr/local/bin/cmux
cmux hooks setup                                             # all detected agents
cmux hooks setup codex|grok|antigravity|opencode             # specific agent
npx skills add manaflow-ai/cmux -g -y                        # install cmux skills for agents
Native session-resume supported for: Claude Code, Codex, Grok, OpenCode, Pi, Amp, Cursor CLI, Gemini, Antigravity, Rovo Dev, Hermes, Copilot, CodeBuddy, Factory, Qoder.
bash
brew tap manaflow-ai/cmux && brew install --cask cmux
sudo ln -sf /Applications/cmux.app/Contents/Resources/bin/cmux /usr/local/bin/cmux
cmux hooks setup                                             # 配置所有检测到的代理
cmux hooks setup codex|grok|antigravity|opencode             # 配置特定代理
npx skills add manaflow-ai/cmux -g -y                        # 为代理安装cmux技能
支持原生会话恢复的代理：Claude Code、Codex、Grok、OpenCode、Pi、Amp、Cursor CLI、Gemini、Antigravity、Rovo Dev、Hermes、Copilot、CodeBuddy、Factory、Qoder。

Socket API (advanced)

Socket API（进阶）

/tmp/cmux.sock
— Unix socket, JSON-RPC v2. Use for tight loops where subprocess spawn cost matters; otherwise prefer the CLI.
bash
echo '{"id":"1","method":"workspace.list","params":{}}' | nc -U /tmp/cmux.sock
Method prefixes: 
system.*
, 
window.*
, 
workspace.*
, 
pane.*
, 
surface.*
, 
notification.*
, 
browser.*
. Full list and Python client example in 
references/socket-api.md
.
Access modes: 
cmuxOnly
(default — only cmux-spawned processes), 
automation
(any local process), 
password
, 
allowAll
(unsafe). If you hit 
Failed to connect to socket
, you're likely an external process under 
cmuxOnly
— switch mode in Settings > Automation or run from inside a cmux terminal.
/tmp/cmux.sock
— Unix套接字，遵循JSON-RPC v2规范。适用于进程启动成本较高的循环场景；否则建议使用CLI。
bash
echo '{"id":"1","method":"workspace.list","params":{}}' | nc -U /tmp/cmux.sock
方法前缀：
system.*
、
window.*
、
workspace.*
、
pane.*
、
surface.*
、
notification.*
、
browser.*
。完整方法列表及Python客户端示例请参考
references/socket-api.md
。
访问模式：
cmuxOnly
（默认——仅允许cmux启动的进程访问）、
automation
（允许任何本地进程访问）、
password
（密码验证）、
allowAll
（不安全）。如果遇到
Failed to connect to socket
错误，你可能是在
cmuxOnly
模式下的外部进程——请在设置>自动化中切换模式，或在cmux终端内运行。

Critical Rules — Non-Disruptive Automation

关键规则 — 无干扰自动化

These rules come from the 
cmux-workspace
skill and prevent agents from yanking the user's focus:
  1. Anchor to 
    CMUX_WORKSPACE_ID
    .     Never assume the visually focused workspace is the target.
  2. Never call focus-changing verbs speculatively. 
    select-workspace
    , 
    focus-pane
    , 
    focus-panel
    , 
    focus-surface
    only on explicit user request. Pass 
    --focus false
    whenever available.
  3. Build layout additively in one call. 
    cmux new-pane --type … --focus false
    beats create-then-move-then-focus chains.
  4. Right-side helper pane pattern. Reuse an existing non-caller helper pane if present; otherwise create exactly one right-side pane.
  5. Never send input to surfaces you don't own. Only target surfaces in the caller's workspace unless the user explicitly asks for cross-workspace routing.
  6. Check surface health before routing input when UI state may be stale: 
    cmux surface-health
    .
这些规则来自
cmux-workspace
技能，用于防止代理干扰用户的焦点：
  1. 以
    CMUX_WORKSPACE_ID
    为锚点    。切勿假设视觉上聚焦的工作区就是目标工作区。
  2. 切勿随意调用改变焦点的操作。仅在用户明确请求时使用
    select-workspace
    、
    focus-pane
    、
    focus-panel
    、
    focus-surface
    。只要有
    --focus false
    参数就传递该参数。
  3. 单次调用完成布局添加。
    cmux new-pane --type … --focus false
    优于创建→移动→聚焦的链式操作。
  4. 右侧辅助窗格模式。如果存在已有的非调用者辅助窗格则复用；否则仅创建一个右侧窗格。
  5. 切勿向非自有界面发送输入。仅针对调用者工作区内的界面，除非用户明确要求跨工作区路由。
  6. 当UI状态可能过时，发送输入前检查界面健康状态：执行
    cmux surface-health
    。

Common Pitfalls

常见陷阱

  • Pi/Pi-like socket connection failures from external processes → default 
    cmuxOnly
    mode; either run inside a cmux terminal or change socket mode.
  • macOS only. No Linux/Windows port.
  • WKWebView ≠ CDP. Don't expect Playwright-equivalent network mocking or viewport emulation.
  • Resume strips sensitive env vars. Re-inject tokens at resume time if the agent needs them.
  • Skills snapshot at app start. Edits to skill files require a restart of the consuming agent.
  • Legacy v1 socket payloads (
    {"command":...}
    ) rejected.     Use v2 JSON-RPC only.
  • Don't 
    cat ~/.cmuxterm/*-hook-sessions.json
     expecting secrets — they're scrubbed. Look there for session/surface mappings only.
  • 外部进程连接Pi/Pi类代理时出现套接字连接失败→ 默认
    cmuxOnly
    模式；请在cmux终端内运行，或切换套接字访问模式。
  • 仅支持macOS。暂无Linux/Windows版本。
  • WKWebView ≠ CDP。不要期望获得与Playwright等效的网络模拟或视口模拟功能。
  • 会话恢复会清除敏感环境变量。如果代理需要令牌，请在恢复时重新注入。
  • 技能在应用启动时快照。修改技能文件后，需重启使用该技能的代理。
  • 旧版v1套接字负载（
    {"command":...}
    ）会被拒绝    。仅使用v2 JSON-RPC格式。
  • 不要通过
    cat ~/.cmuxterm/*-hook-sessions.json
    获取敏感信息    ——这些信息已被清理。仅可在此文件中查看会话/界面映射关系。

Reference: Full CLI Help

参考：完整CLI帮助

For any command, 
cmux <cmd> --help
is authoritative. Use 
cmux capabilities --json
to enumerate available socket methods in the current build.
对于任何命令，
cmux <cmd> --help
是权威参考。使用
cmux capabilities --json
可枚举当前版本中可用的套接字方法。

Keyboard Shortcuts (most-used)

键盘快捷键（常用）

Workspaces: ⌘N new, ⌘1–8 jump, ⌃⌘[ / ⌃⌘] prev/next, ⌘⇧W close, ⌘B sidebar. Surfaces: ⌘T new, ⌘⇧[ / ⌘⇧] prev/next, ⌘W close, ⌃1–8 jump. Splits: ⌘D right, ⌘⇧D down, ⌥⌘D browser right, ⌥⌘←→↑↓ focus directional, ⌘⇧↵ zoom. Browser: ⌘⇧L open, ⌘L address bar, ⌘[/⌘] back/forward, ⌥⌘I devtools. App: ⌘, settings, ⌘⇧, reload-config, ⌘⇧P palette, ⌘⇧O restore session, ⌃⌥⌘. system-wide show/hide.
工作区：⌘N新建，⌘1–8跳转，⌃⌘[ / ⌃⌘]上一个/下一个，⌘⇧W关闭，⌘B显示/隐藏侧边栏。 界面：⌘T新建，⌘⇧[ / ⌘⇧]上一个/下一个，⌘W关闭，⌃1–8跳转。 拆分：⌘D向右拆分，⌘⇧D向下拆分，⌥⌘D向右打开浏览器，⌥⌘←→↑↓方向聚焦，⌘⇧↵缩放。 浏览器：⌘⇧L打开，⌘L地址栏，⌘[/⌘]后退/前进，⌥⌘I开发者工具。 应用：⌘,设置，⌘⇧,重载配置，⌘⇧P命令面板，⌘⇧O恢复会话，⌃⌥⌘.全局显示/隐藏。