cmux CLI 是一套通过命令行操作 cmux 应用的综合工具。当任务适合用 cmux 命令行处理，或用户询问如何使用、检查、脚本化、记录 cmux CLI 时使用本技能。具体语法应优先查阅实时 CLI 帮助，并遵守相关资料给出的安全规则。
【前置条件】 常规用户工作流使用 PATH 上的 cmux 二进制：
cmux --help cmux version cmux ping
在 cmux 源码检出中试用带标签的 Debug 构建时，使用与标签绑定的辅助脚本，而不是 /tmp/cmux-cli：
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh --help CMUX_TAG=<tag> scripts/cmux-debug-cli.sh identify --json
该脚本指向 /tmp/cmux-debug-<tag>.sock，使用带标签应用包中匹配的 CLI，并在运行前清除环境中的 cmux 终端上下文。
【发现命令语法】 给出精确命令帮助前，始终先从 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
有些子命令只打印顶层帮助而非详细子命令帮助。遇到这种情况，在本地源码中搜索。不要用 gh api 拉取源文件，应读取本地检出或活动工作树。
【层级模型】 cmux 通过 Unix socket 暴露应用状态。 Window：顶层 macOS cmux 窗口。 Workspace：窗口中类似侧边栏标签的容器。 Pane：工作区内的分割区域。 Surface：窗格内的标签页，可承载终端、浏览器、markdown 查看器、diff 查看器或其他面板。 Panel：更低层的内容实现，除非命令明确要求 --panel，否则优先使用 surface 命令。 句柄输入通常接受 UUID、ref（如 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
【Socket 定位】 在 cmux 内运行时优先使用调用者环境变量，可通过 printf 打印 CMUX_WORKSPACE_ID、CMUX_SURFACE_ID、CMUX_SOCKET_PATH，并运行 cmux identify --json 确认。对带标签或非默认应用，使用显式 socket 定位：
cmux --socket /tmp/cmux-debug-<tag>.sock identify --json CMUX_SOCKET_PATH=/tmp/cmux-debug-<tag>.sock cmux ping
Socket 认证顺序为：--password，其次 CMUX_SOCKET_PASSWORD，最后 Settings 中保存的密码。在 cmux capabilities --json 或命令错误显示确实需要认证前，不要向用户索要密码。
【全局选项】 常用全局选项包括 --json、--id-format refs/uuids/both、--socket <path>、--password <password>。自动化与脚本使用 --json；面向人的快速状态输出可用普通输出。
【安全的首批命令】 每次自动化会话开始时先检查上下文与能力：
cmux ping cmux capabilities --json cmux identify --json cmux list-windows --json cmux list-workspaces --json cmux tree --all --json
在 cmux 内，默认将变更类命令限定到调用者工作区与表面，例如 list-panes、list-pane-surfaces、read-screen 等。
【常见工作流】 包括：打开但不抢焦点（cmux open . --focus false）；在调用者工作区创建辅助输出（new-pane、new-surface）；读写调用者终端（read-screen、send、send-key）；浏览器表面自动化（browser open、snapshot、click）；设置与文档（docs settings、settings path、config validate、reload-config）；侧边栏任务进度状态（set-status、set-progress、clear-status、clear-progress）。
【命令族】 涵盖：应用/文档/设置类；打开器与查看器；上下文与拓扑；终端 IO（read-screen、send、send-key、capture-pane、pipe-pane、clear-history、respawn-pane）；浏览器自动化（open、goto、snapshot、click、fill、screenshot、get、find、tab、cookies、storage）；通知与侧边栏状态；智能体工作流（hooks、feed、claude-teams、codex-teams、omo、omx、omc）；认证与云（auth、login、logout、vm 或 cloud）；高级 socket/调试（capabilities、events、rpc、surface-health、debug-terminals、trigger-flash）；以及 tmux 兼容命令。
【非干扰式自动化】 用户可能正在看其他工作区、窗口或应用，焦点变化应视同 UI 点击。除非用户明确要求，不要调用 focus-window、focus-pane、focus-panel、select-workspace、会聚焦或选择的 tab-action、right-sidebar focus。优先使用增量、限定范围的命令，并尽可能传 --focus false 或 --no-focus。为任务创建辅助输出时，在调用者工作区复用一个右侧辅助窗格，先用 list-panes 和 list-pane-surfaces 检查，仅在没有合适辅助窗格时才新建。
【设置边界】 cmux 自有设置位于 ~/.config/cmux/cmux.json，Ghostty 终端行为位于 ~/.config/ghostty/config。Ghostty 已支持的终端行为优先用 Ghostty 配置。编辑 cmux.json 前先运行 cmux docs settings 与 cmux settings path，备份为带时间戳的 .bak 副本，然后运行 cmux reload-config。
【调试与带标签构建】 针对 cmux 应用/运行时开发，先构建带标签应用再对其使用 CLI 命令：./scripts/reload.sh --tag <tag>，然后用 CMUX_TAG=<tag> scripts/cmux-debug-cli.sh ...。不要使用没有带标签 -derivedDataPath 的裸 xcodebuild；不要用 /tmp/cmux-cli 做带标签试用。有用的调试文件包括 /tmp/cmux-last-cli-path 与 /tmp/cmux-last-debug-log-path。
【规则】 给出精确语法前先运行 cmux --help 或 cmux <command> --help；脚本与智能体自动化使用 --json；变更类命令用 --workspace、--surface、--pane、--window 限定范围；优先使用 CMUX_WORKSPACE_ID、CMUX_SURFACE_ID、CMUX_SOCKET_PATH；除非用户要求聚焦，否则支持时传 --focus false 或 --no-focus；未先运行 cmux docs settings 或 cmux settings path 不修改设置，编辑 cmux.json 前先备份；Ghostty 已支持的终端行为优先用 Ghostty 配置；带标签 Debug 构建使用 CMUX_TAG=<tag> scripts/cmux-debug-cli.sh ...；任务针对带标签应用时不要对默认 socket 运行命令；CLI 能直接完成设置时不要要求用户粘贴命令。
【相关技能】 skills/cmux/SKILL.md 涵盖核心拓扑与路由；cmux-workspace 技能涵盖当前工作区定位与辅助窗格；cmux-browser 技能涵盖浏览器表面自动化；cmux-config 技能涵盖安全设置编辑；cmux-markdown 技能涵盖 markdown 查看器面板。