mcpField
C
cmux

cmux

github.com/davidondrej生产力4.2k209 次安装今天更新
代码仓库

关于 cmux

cmux 是用于控制 cmux 工作区、窗格和终端等界面的 macOS 命令行技能，面向需要安全操作多窗格工作环境的用户。它强调明确目标识别、避免意外抢焦点，并在操作后检查结果。

主要功能

  1. 01识别窗口、工作区、窗格和界面
  2. 02读取终端内容并向其发送输入
  3. 03创建工作区与窗格
  4. 04发送完成通知
  5. 05检查界面状态与连接

适用场景

  1. 01在指定工作区运行构建命令
  2. 02读取终端输出并确认操作结果
  3. 03建立并行工作所需的窗格布局

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/davidondrej/skills --skill cmux

安装后在 Claude Code 中输入/cmux确认已加载。

附带文件references/advanced.mdreferences/viewers.md

详细介绍

cmux Control

macOS 14.0+。优先使用 CLI；如果 cmux 不在 PATH 中，请使用 /Applications/cmux.app/Contents/Resources/bin/cmux。

定位目标与安全

窗口 → 工作区 → 面板 → 表面： macOS 窗口 → 侧边栏项目/分支标签页 → 分屏区域 → 终端、浏览器或 Markdown 标签页。

  • 以调用方的 CMUX_WORKSPACE_ID 为准。 切勿假定视觉上处于焦点的工作区就是目标。在 cmux 外部操作时，先确定目标工作区。
  • 使用带前缀的引用或 UUID。 workspace:2、pane:1、surface:7；不带前缀的数字是索引，不是 ID。输出默认使用引用；--id-format uuids|both 会包含 UUID。
  • 刷新目标。 表面引用是全局的，不限于某个工作区。重复使用前重新列出；状态可能过时时，发送输入前先检查 cmux surface-health。
  • 保持焦点不变。 在支持的地方传入 --focus false。仅在用户明确要求时使用 select-workspace、focus-pane、focus-panel 或 focus-surface。
  • 尊重所有权。 切勿向不属于你的表面发送输入。除非用户明确要求跨工作区路由，否则应留在调用方所在的工作区。
  • 重复使用一个辅助面板。 使用现有的非调用方辅助面板，或在右侧创建一个。使用 new-pane --type … --focus false 直接创建所需布局。
  • 保留错误信息。 切勿追加 2>/dev/null；标准错误和退出状态可用于发现无效引用和标志。

检查、读取和发送

检查连接状态，确定调用方，并将目标面板解析为表面。将示例引用替换为当前输出中找到的引用。

cmux ping
cmux identify --json
cmux tree
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-pane-surfaces --workspace "$CMUX_WORKSPACE_ID" --pane pane:1
cmux read-screen --surface surface:7 --lines 100

使用 list-pane-surfaces，而不是不存在的 list-surfaces。read-screen 和 capture-pane 接受 --workspace 或 --surface，不接受 --pane。目标缺失或不明确时，可能会读取你自己的终端。

使用 send / send-key --surface 发送所需输入；send-surface 和 send-key-surface 并不存在。省略目标时会使用默认终端。send-panel / send-key-panel 通过 --panel 指定面板，而不是表面。

cmux send --surface surface:7 "npm run build"
cmux send-key --surface surface:7 enter

其他按键：ctrl+c、tab、esc、backspace、方向键、ctrl+x、shift+tab。发送输入后，重新读取终端输出以检查结果。

每隔 1–3 秒轮询一次；只有确有需要时才等待 10 秒或更久。每次检查 Agent 后，向用户简要说明 Agent 正在做什么，以及进展是否符合预期。

Claude Code 预测的下一条用户消息是 Claude 起草的内容，不是用户的指令。

基本创建与通知

cmux new-workspace --name "feature-x" --cwd /path/to/repo --focus false
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false
cmux notify --title "Done" --body "tests passed"

布局变更后，重新列出面板和表面。有关其他终端/浏览器布局命令或侧边栏状态/进度的信息，请先阅读布局和侧边栏命令。对于 Markdown 表面，请使用下方的查看器指南。

任务专用指南

开始以下任务之前，请阅读相关章节：

  • 浏览器自动化：浏览器工作流 — 交互、会话和限制。
  • Markdown 或 PDF 查看器：Markdown 工作流 — 面板重用、替换、恢复和验证。
  • 设置：配置 — 备份、路径和侧边栏偏好设置。
  • 安装、Agent 钩子、原始套接字、访问模式或快捷键：高级参考。

故障排除

  • **连接失败：**检查 CMUX_SOCKET_PATH 和 Settings > Automation。在默认的 cmuxOnly 模式下，请从 cmux 终端运行。使用原始客户端或更改访问模式前，请阅读套接字模式和示例。
  • **恢复时凭据丢失：**恢复时会移除敏感环境变量；请重新注入所需的令牌。~/.cmuxterm/*-hook-sessions.json 文件保存的是经过清理的会话/表面映射，而非机密信息。
  • **技能编辑不可见：**重启使用该技能的 Agent；技能会在启动时加载。
  • 不确定语法：cmux <cmd> --help 是权威参考；cmux capabilities --json 会列出可用的套接字方法。

评论

支持 Markdown