cmux-cli

cmux CLI

在任务最适合通过 cmux 命令行处理，或用户询问如何使用、检查、编写脚本或记录 cmux CLI 时，使用此技能。获取确切语法时优先查看实时 CLI 帮助，然后遵循此处的安全规则。

先决条件

常规用户工作流请使用 PATH 中的 cmux 二进制文件：

cmux --help
cmux version
cmux ping

在 cmux 源代码检出中使用带标签的 Debug 构建进行 dogfooding 时，请使用与标签绑定的辅助脚本，而不是 /tmp/cmux-cli：

CMUX_TAG=<tag> scripts/cmux-debug-cli.sh --help
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh identify --json

scripts/cmux-debug-cli.sh 面向 /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

有些子命令会打印顶层帮助，而不是详细的子命令帮助。如果遇到这种情况，请在本地搜索源代码：

rg -n "Usage: cmux <command>|case \"<command>\"|run.*<Command>" CLI

不要使用 gh api 获取源文件。请读取本地检出或当前工作树中的文件。

心智模型

cmux 通过 Unix 套接字公开应用状态。

• 窗口：顶层 macOS cmux 窗口。
• 工作区：窗口内类似侧边栏标签页的容器。
• 窗格：工作区内的分屏区域。
• 表面：窗格内的标签页。表面可承载终端、浏览器、Markdown 查看器、差异查看器或其他面板。
• 面板：较低层级的内容实现。除非命令明确要求使用 --panel，否则优先使用表面命令。

句柄输入通常接受 UUID、window:1、workspace:2、pane:3、surface:4 等引用，或数字索引。输出默认使用引用：

cmux --id-format refs identify
cmux --id-format both list-pane-surfaces --workspace workspace:1
cmux --json --id-format both tree --all

套接字目标

在 cmux 内运行时，优先使用调用方环境：

printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json

针对带标签或非默认应用，请显式指定套接字目标：

cmux --socket /tmp/cmux-debug-<tag>.sock identify --json
CMUX_SOCKET_PATH=/tmp/cmux-debug-<tag>.sock cmux ping

套接字身份验证按以下顺序解析：--password、CMUX_SOCKET_PASSWORD，然后是 Settings 中保存的密码。在 cmux capabilities --json 或命令错误表明确实需要身份验证之前，不要向用户索要密码。

全局选项

常用全局选项：

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。编写简短的面向用户的状态信息时，请使用普通输出。

安全的首批命令

每次自动化会话开始时，都要检查上下文和功能：

cmux ping
cmux capabilities --json
cmux identify --json
cmux list-windows --json
cmux list-workspaces --json
cmux tree --all --json

在 cmux 内，默认将会修改状态的命令限定在调用方的工作区和表面范围内：

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

常见工作流

更全面的命令目录请参阅 references/commands.md。常用模式：

# Open without stealing focus when supported.
cmux open . --focus false
cmux open https://example.com --workspace "${CMUX_WORKSPACE_ID:-}" --focus false

# Create helper output in the caller workspace.
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

# Read and write the caller terminal.
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

# Browser surface automation.
cmux browser open https://example.com --focus false
cmux browser snapshot --surface surface:5 --compact
cmux browser click "button[type=submit]" --snapshot-after

# Settings and docs.
cmux docs settings
cmux settings path
cmux config validate
cmux reload-config

# Sidebar status for task progress.
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:-}"

命令类别

CLI 包含以下主要类别：

• 应用/文档/设置：welcome、docs、settings、config、shortcuts、reload-config、themes。
• 打开器和查看器：open、markdown、diff、浏览器命令。
• 上下文和拓扑：identify、list-windows、list-workspaces、tree、工作区/窗口/窗格/表面的生命周期命令。
• 终端 IO：read-screen、send、send-key、capture-pane、pipe-pane、clear-history、respawn-pane。
• 浏览器自动化：browser open、goto、snapshot、click、fill、screenshot、get、find、tab、cookies、storage。
• 通知和侧边栏状态：notify、通知列表/读取/清除命令、right-sidebar、set-status、set-progress、log。
• Agent 工作流：hooks、feed、claude-teams、codex-teams、omo、omx、omc。
• 身份验证和云：auth、login、logout、vm 或 cloud。
• 高级套接字/调试：capabilities、events、rpc、surface-health、debug-terminals、trigger-flash。
• tmux 兼容性：capture-pane、resize-pane、wait-for、swap-pane、break-pane、join-pane、find-window、缓冲区、钩子、消息。

非干扰式自动化

用户可能正在查看其他工作区、窗口或应用。应像处理 UI 点击一样处理焦点变化。

除非用户明确要求，否则不要调用以下命令：

• focus-window
• focus-pane
• focus-panel
• select-workspace
• 会聚焦或选择对象的 tab-action 操作
• right-sidebar focus

优先使用增量式、限定范围的命令：

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"

为任务创建辅助输出时，请在调用方工作区复用一个右侧辅助面板。先使用 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 identify --json
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh list-workspaces --json

不要在未指定带标签的 -derivedDataPath 时直接运行 xcodebuild。不要将 /tmp/cmux-cli 用于带标签的内部试用，因为它指向最近重新加载的构建，可能会连接到错误的套接字。

有用的调试文件：

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)"

规则

• 提供精确语法前，先运行 cmux --help 或 cmux <command> --help。
• 在脚本和 Agent 自动化中使用 --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 ...。
• 如果任务涉及带标签的应用，不要对默认套接字运行命令。
• CLI 可以直接完成设置时，不要让用户将命令粘贴到 cmux 中运行。

相关技能

• skills/cmux/SKILL.md 涵盖核心拓扑和路由。
• cmux-workspace 技能涵盖当前工作区定位和辅助面板。
• cmux-browser 技能涵盖浏览器界面自动化。
• cmux-config 技能涵盖安全编辑设置。
• cmux-markdown 技能涵盖 Markdown 查看器面板。