用途
cmux 是一个通过 Unix 套接字 CLI 控制的终端复用器,负责管理窗口(window)、工作区(workspace)、窗格(pane)和界面(surface)。该技能供 AI 代理(如 Claude Code)在需要创建隔离终端窗格执行并行任务、发送命令、读取输出并在完成后清理时调用。
核心概念
- 窗口:顶层操作系统窗口,可用
cmux list-windows列出。 - 工作区:窗口内的一个标签页,拥有自己的窗格布局,用
cmux new-workspace创建,cmux select-workspace切换。 - 窗格:工作区内矩形的分屏区域,包含一个或多个界面,用
cmux new-pane --direction <dir>创建。 - 界面:窗格内实际的终端(或浏览器)实例,形如
surface:42,是发送命令和读取输出的对象。 - 引用格式:短引用如
pane:5、surface:12、workspace:3,可通过--id-format uuids输出 UUID,--id-format both同时输出两者。
主要能力
- 识别上下文:
cmux --json identify返回调用者的 surface_ref、pane_ref、workspace_ref、window_ref。 - 创建分屏窗格:
cmux --json new-pane --direction right(右分屏)或--direction down(下分屏),可加--workspace workspace:3指定工作区,返回新窗格及其界面引用。 - 发送命令:
cmux send --surface surface:42 "npm test"只输入文本不回车,需配合cmux send-key --surface surface:42 Enter执行;也支持 Escape、Tab、ctrl+c、ctrl+d、Up、Down 等按键。 - 读取屏幕:
cmux read-screen --surface surface:42,可加--scrollback包含回滚缓冲,--lines 50只取最后 N 行。 - 关闭界面:
cmux close-surface --surface surface:42。 - 列表与焦点:
cmux --json list-panes、cmux --json list-pane-surfaces --pane pane:5、cmux focus-pane --pane pane:5。 - 工作区管理:列出、创建(可带
--command启动命令)、切换、重命名、关闭、获取当前工作区。 - 通知:
cmux notify --title "Task Complete" --body "All tests passed"。
环境变量
cmux 在其创建的每个终端中自动设置:
CMUX_WORKSPACE_ID:所有命令的默认--workspaceCMUX_SURFACE_ID:命令的默认--surfaceCMUX_TAB_ID:tab-action/rename-tab 的默认--tabCMUX_SOCKET_PATH:覆盖套接字路径(默认/tmp/cmux.sock)
因此在 cmux 内部运行时,多数命令无需显式指定 ID。
使用方式
所有命令统一为 cmux [--json] <command> [options],程序化解析输出时应始终加 --json。典型子代理工作流:先 identify 确认位置,再 new-pane 创建分屏并取得界面引用,用 send 加 send-key Enter 执行任务,随后 read-screen --scrollback 读取结果,最后 close-surface 清理。并行子代理可重复该流程,用 right、down 等不同方向形成网格布局。
适用场景
- 为子代理任务或多代理并行开发创建隔离终端窗格
- 向指定终端界面发送命令与按键、读取屏幕内容
- 编排多窗格布局、创建与管理工作区
- 在终端窗格旁打开浏览器界面
- 重命名、重排或在 工作区之间移动界面/窗格
不适用于与 cmux 无关的普通 shell 脚本,也不适用于 tmux 或 screen 命令(cmux 有独立协议)。
限制与注意事项
send不按回车:只输入文本不执行,必须随后send-key ... Enter,否则 read-screen 只看到输入没有输出。- 读取长输出需
--scrollback:命令输出滚出可见区域后,不加该参数可能只返回 shell 提示符。 - 引用会失效:工作区关闭后其所有界面引用失效,报 "Surface not found",发送前应重新
list-panes。 - 嵌套环境套接字路径可能不继承:在子 shell 或 sudo 中
CMUX_SOCKET_PATH可能未传递,需显式--socket-path。 close-surface关闭的是界面而非窗格,误关会静默移除仍需要的终端,关闭前应用list-pane-surfaces核验引用。- 常见错误:套接字未找到(应用未运行或路径错误)、界面未找到、工作区未找到、认证失败(套接字密码不匹配,可设
CMUX_SOCKET_PASSWORD或--password)。
参考资料
详细内容分文件存放:references/pane-management.md(窗格高级操作:调整大小、交换、拆分、合并、拖拽分屏、面板)、references/browser-automation.md(浏览器界面的打开、导航、快照、点击、填表、执行 JS)、references/subagent-workflows.md(多代理编排、并行任务执行、输出轮询、清理策略)。仅在任务需要时加载,避免消耗上下文。
首次激活时会检查已安装的配套技能,缺失时提示安装:npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>。