创建日期：2026-09-14 ｜ 最近更新：2026-09-14 事实核对基于 npm
cmux@0.11.0（本机实测：下载包、读启动器源码、跑--help/--version）。说明：cmux 的 TUI 需要真实终端，本机沙箱无法启动会话（实测报Operation not permitted），所以「使用」部分是真实抓取的命令帮助，未逐条执行——本文不含编造的运行结果。
cmux 入门与使用：不只是 tmux 替代，而是「给 Agent 的资源客户端」
一句话：cmux 是一个终端复用器（TUI），但它的野心不止于此——它把自己定位成 terminal multiplexer and resource client：把「工作区 / 面板 / 终端 / 浏览器 / 通知 / Agent 状态」都抽象成可寻址、可 JSON 化的资源，让你（或一个 Agent）用命令行去读写它们。
它用 Rust 写成、底层是 libghostty-vt（Ghostty 的终端 VT 库），通过 npm 分发。如果你做过「让 AI 操作终端/浏览器」的事（本站 frontend-agent 手写过工具循环），cmux 提供的是现成的资源层 + CLI 接口。
1. 它到底是什么
三个层次，从广告词开始理解：
| 层次 | 说明 |
|---|---|
| TUI 复用器 | 像 tmux 一样：会话、工作区、面板、标签页；cmux 直接进交互界面 |
| 资源客户端（重点） | cmux <scope> <action> 把终端/浏览器/通知等当资源操作；支持 --json / --jsonl |
| Agent 基础设施 | agent scope（状态上报 + hook 安装）、remote rpc（跑 workspace 里的 coding-agent 请求）、session journal（带过滤的事件日志） |
和 tmux 的关键差别：
| tmux | cmux | |
|---|---|---|
| 主要给谁用 | 人 | 人 + Agent/脚本 |
| 输出 | 终端画面 | 终端画面 + JSON/JSONL |
| 资源类型 | 窗口/面板 | 工作区/浏览器/标签/通知/Agent 状态 |
| 事件 | 无 | session journal subscribe（可按 kind/敏感度/正则过滤） |
2. 安装与运行
npx cmux # 直接跑（会下载对应平台的二进制）
npm i -g cmux # 或全局安装，之后用 cmux 命令
实测版本输出（真实）：
$ npx cmux --version
cmux 0.1.0 (35cbaa63ce5c2768a0f64af2cf1eeb06d719232d; ghostty 3da10da73ae848c0310e3e0f0cb29e509c2f6963)
注意这个「版本差」：npm 包版本是 0.11.0，二进制自报的是 cmux 0.1.0（后面跟 git 哈希与 ghostty 哈希）。npm 版本号是发布节奏，二进制版本是程序自身——排查问题时报
--version的完整串即可。
它是怎么分发的（读了启动器源码）
npm 包本体很小，只有一个启动器 bin/cmux.js（Node ≥ 18）：
// 平台 → 二进制包的映射（摘自 bin/cmux.js）
const PACKAGE_BY_PLATFORM = {
"darwin-arm64": "cmux-tui-darwin-arm64",
"darwin-x64": "cmux-tui-darwin-x64",
"linux-x64": "cmux-tui-linux-x64",
"linux-arm64": "cmux-tui-linux-arm64",
// win32-x64 pending: ghostty vt headers fail bindgen under mingw clang.
};
真正的程序是预编译 Rust 二进制，放在按平台拆分的 optionalDependencies 里；npm 只装匹配当前 os+cpu 的那一个，启动器负责 spawnSync 并转发 argv/stdio/退出码与信号。
由此得到两个实用结论：
- 目前只支持 macOS(arm64/x64) 与 Linux(x64/arm64)，Windows 还没有（源码注释里写了原因：mingw clang 下 ghostty vt 头文件 bindgen 失败）；
- 如果你的 npm 配置跳过了可选依赖，运行会提示：
platform package … is not installed. Reinstall cmux, or set npm to install optional dependencies (--include=optional)。 —— 这正是我实测时会遇到的报错文本。
3. 前提：它需要「真实终端」
这点必须先讲，否则你会以为它坏了。cmux 的 TUI 要一个真正的 TTY，我的两次实测：
# 直接在无 TTY 的环境里跑
$ npx cmux
cmux-tui: Device not configured (os error 6)
# 想在沙箱里起一个无头会话
$ npx cmux --socket /tmp/cmux-lab.sock server start
cmux-tui: Operation not permitted (os error 1)
所以你要用它，请在本地终端（iTerm/Terminal/VS Code 内置终端）里跑；本文的「使用」清单来自 --help，不是沙箱里的运行结果——这一点我不含糊。
4. 概念模型：会话 → 工作区 → 面板 → 标签
cmux 的层级（官方 --help 里的 RESOURCE SCOPES）：
session（会话，默认 main；决定 socket 路径）
└─ workspace（工作区）
└─ screen（屏幕）
└─ pane（面板，可 split --right / --down）
└─ tab（标签页）：terminal 或 browser
围绕它还有几个运行单元：
| scope | 作用 |
|---|---|
server | 本地「durable 会话 owner」：start/status/stop/reload-config |
remote | 远程守护进程：connect/ssh/forward/rpc/enroll/known-daemons/stop |
relay | 通过 stdio 转发协议字节（便于被别的进程托管） |
machine-agent | 把本地会话通过配置的 host 共享出去 |
client / machine | 看客户端与机器/路由信息 |
5. 使用：命令速查（摘自真实 --help）
5.1 启动与连接
cmux # 起一个会话（默认 session=main）
cmux --session dev # 指定会话名（决定 socket 路径）
cmux --socket /tmp/cmux.sock # 显式指定 socket
cmux attach [OPTIONS] # 附着到会话/某个终端
cmux server start|status|stop|reload-config # 本地会话服务
5.2 把「终端」当资源操作（terminal）
cmux terminal list
cmux terminal <selector> screen read # 读屏
cmux terminal <selector> screen wait --pattern <regex> --timeout-ms N # 等某个输出出现
cmux terminal <selector> write --text "ls -al" # 写入
cmux terminal <selector> keys <key...> # 发按键
cmux terminal <selector> history read | copy | process wait
screen read+screen wait --pattern这对组合，几乎是「让 Agent 等命令跑完」的标准动作——等价于你手写循环里的「读输出、判断完成」。
5.3 工作区 / 面板 / 标签
cmux workspace list
cmux workspace create --name demo
cmux workspace <selector> run -- npm run dev # 在工作区里跑命令
cmux workspace <selector> run shell 'echo hi && pwd'
cmux pane <selector> split --right --ratio 0.3
cmux pane <selector> focus direction left
cmux tab create terminal
cmux tab create browser --url https://example.com # ★ 内置浏览器标签
5.4 浏览器也是资源（browser）
cmux browser list
cmux browser <selector> navigate <url>
cmux browser <selector> back|forward|reload|activate
cmux browser <selector> key|text [OPTIONS] # 输入
cmux browser <selector> mouse|wheel --pointer-frame-seq <decimal>
cmux browser <selector> attach | close
这是 cmux 最不像 tmux 的地方：浏览器标签与终端面板是同级的「可寻址资源」，所以「让 Agent 开个网页、点一下、读结果」是原生能力。
5.5 给 Agent 用：agent scope 与 JSON 输出
cmux agent list
cmux agent report --terminal <selector> --state <value> --source <value>
cmux agent hook install|uninstall|status [provider...]
cmux agent hook emit --source <agent> --event <native-event> [--terminal <id>]
# 全局开关：让一切可编程
cmux --json workspace list # 一条 JSON 结果
cmux --jsonl session <sel> journal subscribe # 每行一个事件
cmux --quiet ... # 只关心退出码/副作用时
再加 session journal subscribe（支持 --kinds/--classes/--subjects/--regex/--max-sensitivity 过滤）——一个带过滤能力的事件流，适合做「Agent 行为审计/回放」。
6. 什么时候值得用它
- 你在做「会操作终端/浏览器」的 Agent：与其自己
child_process+ Playwright 拼，不如把 cmux 当资源层，用--json编排； - 你想让远程/多机会话统一管理：
remote connect/ssh/forward+server的 durable session； - 你只想要一个好用的 TUI 复用器：也能用，但要接受它「概念比 tmux 多」。
什么时候不必：只想要最简单终端复用 → tmux/zellij 更成熟；只做浏览器自动化 → Playwright 更直接。
7. 坑与注意（实测/源码得来）
- 必须有 TTY：无 TTY 报
Device not configured (os error 6)；受限环境报Operation not permitted (os error 1)； - 平台限制：仅 macOS/Linux（Windows pending）；跳过 optionalDependencies 会启动失败；
- npm 版本 ≠ 二进制版本（0.11.0 vs 0.1.0），报版本时给完整串；
- 概念比 tmux 多：workspace/screen/pane/tab 四层 + 资源 scope，建议先
cmux --help再cmux <scope> --help逐步探索（本文的清单就是这么来的）。
关联
- 自己做 Agent 工具循环的对照：frontend-agent 系列（
screen wait --pattern对应的就是「读输出判断完成」） - 工具协议视角：MCP 入门（cmux 的
relay/stdio 转发也是同类思路）
参考
- 仓库：github.com/manaflow-ai/cmux
- npm：npmjs.com/package/cmux（0.11.0，MIT）
- 本文命令清单来自本机
npx cmux --help及各scope --help的真实输出；TUI 行为因沙箱无 TTY 未实测，请以你本地运行为准。