cmux CLI 使用与自动化：发现语法、安全限定作用域…

当需要通过 cmux 命令行检查、脚本化或自动化 cmux app 的 workspace/pane/surface/browser/settings 等状态时使用。

适用场景

解决思路

1. 普通用户工作流优先使用 PATH 上的 `cmux` 二进制：运行 `cmux --help`、`cmux version`、`cmux ping`。
2. 当对 cmux 源码 checkout 中带 tag 的 Debug 构建进行 dogfooding 时，使用 tag 绑定 helper 而不是 `/tmp/cmux-cli`：运行 `CMUX_TAG=<tag> scripts/cmux-debug-cli.sh --help` 和 `CMUX_TAG=<tag> scripts/cmux-debug-cli.sh identify --json`。
3. 理解 `scripts/cmux-debug-cli.sh` 会指向 `/tmp/cmux-debug-<tag>.sock`，使用来自 tagged app bundle 的匹配 CLI，并在运行前清理 ambient cmux 终端上下文。
4. 在给出确切命令帮助前，始终通过 CLI 发现当前语法：运行 `cmux --help`、`cmux help`、`cmux <command> --help`、`cmux docs settings`、`cmux docs shortcuts`、`cmux docs api`、`cmux docs browser`、`cmux docs agents`、`cmux docs dock`。
5. 如果某些子命令只打印顶层帮助而不是详细子命令帮助，在本地搜索源码：运行 `rg -n "Usage: cmux <command>|case \"<command>\"|run.*<Command>" CLI`；不要用 `gh api` 拉取源码文件，读取本地 checkout 或活动 worktree。
6. 牢记模型：cmux 通过 Unix socket 暴露 app 状态；Window 是顶层 macOS cmux 窗口，Workspace 是窗口内 sidebar tab-like 容器，Pane 是 workspace 内 split region，Surface 是 pane 内 tab，可承载 terminal、browser、markdown viewer、diff viewer 或其他 panel，Panel 是更低层内容实现；除非命令明确要求 `--panel`，优先使用 surface 命令。
7. Handle 输入通常接受 UUID、refs（如 `window:1`、`workspace:2`、`pane:3`、`surface:4`）或数字索引；输出默认是 refs；使用 `cmux --id-format refs identify`、`cmux --id-format both list-pane-surfaces --workspace workspace:1`、`cmux --json --id-format both tree --all`。
8. 在 cmux 内运行时优先使用调用者环境：运行 `printf 'workspace=%s\nsurface=%s\nsocket=%s\n' "${CMUX_WORKSPACE_ID:-}" "${CMUX_SURFACE_ID:-}" "${CMUX_SOCKET_PATH:-}"` 和 `cmux identify --json`。
9. 对 tagged 或非默认 app 使用显式 socket targeting：运行 `cmux --socket /tmp/cmux-debug-<tag>.sock identify --json` 和 `CMUX_SOCKET_PATH=/tmp/cmux-debug-<tag>.sock cmux ping`。
10. Socket auth 解析顺序为 `--password`，然后 `CMUX_SOCKET_PASSWORD`，然后 Settings 中保存的密码；直到 `cmux capabilities --json` 或命令错误显示确实需要 auth 时，才向用户索要密码。
11. 常用全局选项：`cmux --json <command>`、`cmux --id-format refs <command>`、`cmux --id-format uuids <command>`、`cmux --id-format both <command>`、`cmux --socket <path> <command>`、`cmux --password <password> <command>`；自动化和脚本用 `--json`，快速面向人类的状态用普通输出。
12. 每个自动化会话先用安全首选命令检查上下文和能力：`cmux ping`、`cmux capabilities --json`、`cmux identify --json`、`cmux list-windows --json`、`cmux list-workspaces --json`、`cmux tree --all --json`。
13. 在 cmux 内默认将变更命令限定到调用者 workspace 和 surface：`cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json`、`cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json`、`cmux read-screen --workspace "${CMUX_WORKSPACE_ID:-}" --surface "${CMUX_SURFACE_ID:-}" --lines 80`。
14. 打开时不抢焦点（若支持）：`cmux open . --focus false`、`cmux open https://example.com --workspace "${CMUX_WORKSPACE_ID:-}" --focus false`。
15. 在调用者 workspace 中创建 helper 输出：`cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false`、`cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 --type terminal --focus false`。
16. 读取和写入调用者终端：`cmux read-screen --surface "${CMUX_SURFACE_ID:-}" --scrollback --lines 200`、`cmux send --surface "${CMUX_SURFACE_ID:-}" "echo ok\n"`、`cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter`。
17. Browser surface 自动化：`cmux browser open https://example.com --focus false`、`cmux browser snapshot --surface surface:5 --compact`、`cmux browser click "button[type=submit]" --snapshot-after`。
18. 设置和文档：`cmux docs settings`、`cmux settings path`、`cmux config validate`、`cmux reload-config`。
19. Sidebar 任务进度状态：`cmux set-status build running --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"`、`cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"`、`cmux clear-status build --workspace "${CMUX_WORKSPACE_ID:-}"`、`cmux clear-progress --workspace "${CMUX_WORKSPACE_ID:-}"`。
20. 命令族包括：App/docs/settings：`welcome`、`docs`、`settings`、`config`、`shortcuts`、`reload-config`、`themes`；Openers/viewers：`open`、`markdown`、`diff`、browser commands；Context/topology：`identify`、`list-windows`、`list-workspaces`、`tree`、workspace/window/pane/surface lifecycle commands；Terminal IO：`read-screen`、`send`、`send-key`、`capture-pane`、`pipe-pane`、`clear-history`、`respawn-pane`；Browser automation：`browser open`、`goto`、`snapshot`、`click`、`fill`、`screenshot`、`get`、`find`、`tab`、cookies、storage；Notifications/sidebar state：`notify`、notification list/read/clear commands、`right-sidebar`、`set-status`、`set-progress`、`log`；Agent workflows：`hooks`、`feed`、`claude-teams`、`codex-teams`、`omo`、`omx`、`omc`；Auth/cloud：`auth`、`login`、`logout`、`vm` 或 `cloud`；Advanced socket/debug：`capabilities`、`events`、`rpc`、`surface-health`、`debug-terminals`、`trigger-flash`；tmux compatibility：`capture-pane`、`resize-pane`、`wait-for`、`swap-pane`、`break-pane`、`join-pane`、`find-window`、buffers、hooks、messages。
21. 非破坏性自动化：用户可能正在看不同的 workspace、window 或 app；把焦点变化当作 UI 点击；除非用户明确要求，不要调用 `focus-window`、`focus-pane`、`focus-panel`、`select-workspace`、会 focus 或 select 的 `tab-action`、`right-sidebar focus`。
22. 优先使用 additive、scoped 命令：`cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false`、`cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 --type terminal --focus false`、`cmux send --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:7 "npm test\n"`。
23. 为任务创建 helper 输出时，在调用者 workspace 中复用一个右侧 helper pane；先用 `list-panes` 和 `list-pane-surfaces`，仅当没有合适 helper pane 时才创建新 pane。
24. Settings 边界：cmux 自有设置位于 `~/.config/cmux/cmux.json`；Ghostty 终端行为位于 `~/.config/ghostty/config`；Ghostty 已支持的终端行为（如 font、cursor style、scrollback、theme、background opacity、blur）优先用 Ghostty config。
25. 编辑 `cmux.json` 前运行 `cmux docs settings` 和 `cmux settings path`；编辑前将现有文件备份到带时间戳的 `.bak` 副本，然后运行 `cmux reload-config`。
26. Debug 和 tagged builds：针对 cmux app/runtime 开发，先构建 tagged app 再对其使用 CLI 命令：`./scripts/reload.sh --tag <tag>`、`CMUX_TAG=<tag> scripts/cmux-debug-cli.sh identify --json`、`CMUX_TAG=<tag> scripts/cmux-debug-cli.sh list-workspaces --json`。
27. 不要在没有 tagged `-derivedDataPath` 的情况下使用裸 `xcodebuild`；不要用 `/tmp/cmux-cli` 做 tagged dogfood，因为它指向最近 reload 的 build，可能目标错误 socket。
28. 有用的 debug 文件：`cat /tmp/cmux-last-cli-path`、`cat /tmp/cmux-last-debug-log-path`、`tail -f "$(cat /tmp/cmux-last-debug-log-path 2>/dev/null || echo /tmp/cmux-debug.log)"`。
29. 规则：在给出确切语法前运行 `cmux --help` 或 `cmux <command> --help`。
30. 规则：脚本和 agent 自动化用 `--json`。
31. 规则：对变更命令尽可能用 `--workspace`、`--surface`、`--pane`、`--window` 限定作用域。
32. 规则：优先使用 `CMUX_WORKSPACE_ID`、`CMUX_SURFACE_ID`、`CMUX_SOCKET_PATH` 而不是 focused-window fallbacks。
33. 规则：只要命令支持，传 `--focus false` 或 `--no-focus`，除非用户要求 focus 某物。
34. 规则：绝不在未先运行 `cmux docs settings` 或 `cmux settings path` 的情况下更改设置；编辑前备份 `cmux.json`。
35. 规则：Ghostty 已支持的终端行为优先用 Ghostty config。
36. 规则：对 tagged Debug builds，使用 `CMUX_TAG=<tag> scripts/cmux-debug-cli.sh ...`。
37. 规则：当任务关于 tagged app 时，不要对默认 socket 运行命令。
38. 规则：当 CLI 能直接完成设置时，不要让用户把命令粘贴到 cmux。
39. 相关技能参考：`skills/cmux/SKILL.md` 覆盖核心 topology 和 routing；`cmux-workspace` skill 覆盖 current-workspace targeting 和 helper panes；`cmux-browser` skill 覆盖 browser surface automation；`cmux-config` skill 覆盖 safe settings edits；`cmux-markdown` skill 覆盖 markdown viewer panels。

适用边界 · 注意事项

• 当任务与 cmux CLI 无关，或环境中没有 `cmux` 二进制/Unix socket 时，不适用。
• 当任务针对 tagged Debug 构建时，不要用默认 socket、`/tmp/cmux-cli` 或没有 tagged `-derivedDataPath` 的裸 `xcodebuild`。
• 除非用户明确要求，不要改变焦点；不要把 `focus-window`、`focus-pane`、`focus-panel`、`select-workspace` 等焦点命令当作普通自动化步骤。