🖥️ tmuxes

简体中文 ｜ English

一个浏览器标签页，掌控一整群 CLI coding agent。

Claude Code · Codex · OpenCode · Hermes —— 每个 agent 独占一个 tmux 会话，
横跨 本地 · SSH · WSL，还自带每个 agent 工作目录的文件浏览器。

🔔 Claude Code / Codex 结束运行、异常停止或需要决策时,浏览器会自动提醒你 —— 侧边栏红/绿状态点 +「结束 / 决策 / 错误」提示 + 提示音 + 后台标签页标题闪烁。再也不用挨个窗格去盯「它还在跑吗」。

_{🔒 仅本机 · ⚡ 一键启动 · 🔔 agent hook 提醒 · 🪟 Windows 上直通 WSL · 🧩 零配置}

为什么做这个？ 现代编码 agent 都是常驻的终端进程。同时跑好几个，你就开始在一堆窗格、SSH 窗口之间手忙脚乱：
「等等，刚那个是在哪台机器上来着？」tmuxes 把它们全塞进一个清爽的网页 UI：
开一个会话、丢进文件夹、看它干活、顺手瞄一眼它正在改的文件 —— 本地还是远程，都是同一个视图。

✨ 特性亮点


🧠 为 agent 而生	每个 agent 独占一个 tmux 会话。新建时可带初始命令（比如 `claude` 或 `codex`），选中后右侧就是一个完全可交互的实时终端。
🔔 结束 / 决策 / 错误提醒	新建会话时初始命令是 `claude` 或 `codex` 会自动接入官方 lifecycle hooks。也可以先进入空 session `cd` 到目标目录,再点终端右上角的 `claude` / `codex` 按钮启动带 hook 的 agent。已展开目标每 5 秒同步一次:红点表示 agent 正在运行,绿点表示已结束、异常停止或正在等你决策;结束运行、需要决策和异常停止会显示不同提示。
🌐 本地 · SSH · WSL · 原生 Windows	一个侧边栏同时列出你的本机、`~/.ssh/config` 里的主机、（Windows 上）你的 WSL 发行版，以及（Windows）原生 PowerShell / cmd 会话 —— 全部并排排开。
🗂️ 文件夹树	像资源管理器一样，把会话拖进可拖拽的文件夹里整理。按目标分别持久化到本地。
📂 实时文件浏览 + 编辑	侧边栏底部跟随每个会话的工作目录 —— 点一个代码文件就能把终端一分为二，在下面直接读和改（可保存、撤销/重做）。
🔁 真·多端同步	基于原生 `tmux attach`：同一个会话开两个标签页，逐键同步、互为镜像。
⚙️ 可调	侧边栏、终端、文件查看器的字号都能调，实时生效、刷新后仍保留。
🚀 一键启动	双击 `start.cmd` / `start.command` / `start.sh` → 自动构建、启动、打开浏览器。

🖼️ 长这样

🏗️ 架构

                          REST  (create · list · rename · kill · cwd · files)
  ┌────────────┐   ┌──────────────────────┐        ┌──────────────────────────────────┐
  │  Browser   │──▶│  Node · Express · ws │──pty──▶│ tmux                  (Linux/macOS)│
  │  xterm.js  │◀──│        node-pty      │──pty──▶│ ssh -tt user@host → tmux   (remote)│
  └────────────┘   └──────────────────────┘──pty──▶│ wsl.exe -d <distro> → tmux (Windows)│
        ▲   binary bytes ⇄ WebSocket ⇄ JSON control └──────────────────────────────────┘

client/ —— React + Vite + TypeScript，终端基于 @xterm/xterm。
server/ —— Node + Express + ws + node-pty。一个小型 REST API 跑短命的 tmux 管理命令；单个 WebSocket 端点负责交互式 attach 的流式传输。

Windows 上没有原生 tmux？ 没问题。服务端原生运行（node-pty 用 ConPTY），通过 wsl.exe 直通你 WSL 发行版里的 tmux。Linux/macOS 上则直接和本地 tmux 通信。远程主机用系统 ssh 二进制，复用你已有的 ~/.ssh 密钥 / ssh-agent —— 绝不存储任何密码。

📦 用 npm 安装

建议直接用 @latest，这样能拿到最新的修复包。tmuxes 是单用户本机工具，启动后只监听 127.0.0.1。

# 先验证 npm 包入口:
npx --yes tmuxes@latest --help

# 一键运行(无需克隆,默认自动开浏览器):
npx --yes tmuxes@latest

# 或全局安装后用 tmuxes 命令:
npm install -g tmuxes
tmuxes                       # → http://127.0.0.1:7420

# 常用参数:
tmuxes --port 8080 --no-open

如果 Windows 上 npx 失败，先确认：

node -v 是 22.12+ 且 <23，npm -v 是 10+。
使用的是官方 npm registry，且没有旧缓存污染；必要时先跑 npm cache verify 再重试。
你要连接的机器/主机上已经装好 tmux。Linux 上 node-pty 需要现场编译，先装 build-essential + python3；Windows / macOS 使用预编译二进制。

🚀 从源码一键启动(开发用)

系统	怎么做
🪟 Windows 11	双击 `start.cmd`（或在 Windows Terminal 里运行）。自动装依赖、构建、启动服务，并打开 `http://127.0.0.1:7420`。你的 WSL 发行版会出现在侧边栏。
🍎 macOS	在访达里双击 `start.command` _{（首次：右键 → 打开，绕过 Gatekeeper）}。
🐧 Linux	运行 `./start.sh`。

🔧 手动运行

npm install            # node-pty：Win/macOS 有预编译，Linux 从源码编译

# 开发 —— Vite 开发服务器 + API，带热更新：
npm run dev            # → http://localhost:5173

# 生产 —— 构建客户端，由单进程统一服务：
npm run build
npm start              # → http://localhost:7420   （设 TMUXES_OPEN=1 可自动打开浏览器）

🔔 启动带 hook 的 Claude Code / Codex

tmuxes 目前会给 Claude Code (claude) 和 Codex (codex) 自动接入官方 lifecycle hooks，用来判断 agent 是正在运行、已经结束、异常停止，还是正在等你做决策。

两种用法：

新建 session 时，在初始命令里直接填 claude 或 codex。
先新建空 session，进入后在终端里 cd /你的目标目录，再点终端右上角的 claude / codex 按钮。

状态含义：

红点：agent 正在运行。
绿点：agent 已结束、异常停止、正在等你决策，或这个 session 没接入 agent hook。
结束 badge：本轮运行结束。
决策 badge：agent 正在等待权限确认或用户输入。Codex 开启 approvals_reviewer = "auto_review" / Approve for me 时，普通审批请求会交给 Codex 自动 reviewer，不会被误判成需要你手动决策。
错误 badge：agent 异常停止，例如 Codex 断流但没有触发 stop hook。tmuxes 会在已展开目标的 5 秒同步里扫描 running agent 的 pane 尾部并把这类错误纠正为提醒状态。

注意：右上角按钮本质上是向当前 tmux pane 发送一条带 hook 的 claude / codex 命令。不要在当前 pane 里已有程序正在接收输入时点击它。裸 cc 常常是系统 C 编译器，tmuxes 不会默认把它当作 Claude Code。原生 Windows shell 没有 tmux session option，因此不支持这套 hook 状态。

🧩 目标（Targets）

本地 (Linux/macOS) —— 你机器上的 tmux。Windows 上不显示。
Windows 本机终端 (Windows) —— 服务端用 ConPTY 直接开 PowerShell / cmd 等本机 shell（自动探测 pwsh → powershell → cmd → Git Bash），新建时可在下拉里选 shell。会话随服务端进程存活（刷新 / 重连 / 多标签都不丢，重启服务端会丢）；这类会话没有 tmux 工作目录，故隐藏底部文件浏览器。
WSL 发行版 (Windows) —— 通过 wsl.exe -l -q 自动发现；每个发行版一个目标。发行版里必须装了 tmux。
SSH 主机 —— 从你的 ~/.ssh/config 的 Host 条目里发现（跳过通配符）。也可显式添加：
```
TMUXES_HOSTS="alice@web1,bob@db2:2222" npm run dev      # Linux / macOS
set TMUXES_HOSTS=alice@web1,bob@db2:2222 && npm run dev # Windows cmd
```
密钥 / agent 认证必须在普通 shell 里已经能用。全新主机请先在普通终端里接受一次它的 host key。为避免短命管理命令反复新建 SSH 连接，类 Unix 平台会通过 OpenSSH ControlMaster / ControlPersist 长期复用同一条 SSH 连接；原生 Windows 则由 tmuxes 维护一条应用层 SSH 管理长连接，不使用 Windows OpenSSH mux socket，避免 getsockname failed: Not a socket。tmuxes 不再强制设置 ServerAliveInterval，如需保活请按所在平台规则写进你自己的 ~/.ssh/config。如果复用 / 管理连接中断，tmuxes 会自动重建并重试一次；仍失败时会在前端页面提示并暂停该 SSH 目标的自动轮询，点击 Reconnect 可手动再试一次。

💻 环境要求

所有平台都需要 Node 22.12+（项目版本文件固定为 22.22.2）和 npm 10+。其余：

🪟 Windows 11

WSL2 且至少一个发行版，并在其中装好 tmux（sudo apt install tmux）。
内置的 OpenSSH 客户端覆盖 SSH 目标。
node-pty 提供预编译 Windows 二进制 —— 不需要编译器。

🍎 macOS

tmux 在 PATH 上（brew install tmux）。
node-pty 提供预编译 darwin 二进制。
从访达启动却找不到 tmux？确保 Homebrew 的 bin 目录在 GUI 的 PATH 里。

🐧 Linux

tmux，外加给 node-pty 的 C/C++ 工具链 + Python 3（没有 Linux 预编译 —— 安装时现场编译）：
```
sudo apt-get install -y build-essential python3 tmux
```
WSL 小坑：node-gyp 会用 PATH 上的任意 python3。如果坏掉的 conda Python 把构建搞挂了：
```
npm config set python /usr/bin/python3
```

（备选）把服务端跑在 WSL 内部

在 Windows 上，你也可以把整个服务端跑在 WSL 内部（像 Linux 一样），然后在 Windows 上开浏览器 —— WSL2 会转发 localhost。一键启动脚本用的是「原生 Windows + wsl.exe」方案，这样能在一个地方同时覆盖 SSH 目标和多个发行版。

🔒 安全

⚠️ tmuxes 会把完整的 shell 访问权交给任何能连上它的人。 它是一个单用户、仅本机的开发工具。

设计上它：

只绑定 127.0.0.1 —— 绑定地址在运行时不可配置，
没有任何认证，
从不起 shell（argv 数组 + shell:false），并对每个输入做白名单校验，
拒绝 Origin 非 localhost 的 WebSocket 升级（防 DNS-rebind），
把文件浏览器 / 编辑器限制在所选 tmux 会话的当前工作目录之内。

请勿对它做反向代理、隧道、端口转发，或暴露到 0.0.0.0。机器上任何本地用户都能用它。

🧪 测试

npm test   # vitest：输入校验、列表解析、ssh/tmux/wsl 的 argv 形状

🐧 tmux 速查表

tmux 的「前缀键」默认是 Ctrl+b（下面记作 C-b）—— 先按它，松开，再按后面的键。
在网页终端里最常用的是滚动 / 复制模式（往上看历史输出、复制文字）。

滚动 & 复制（最常用）

操作	按键
进入复制 / 滚动模式	`C-b` 然后 `[`
在模式里上下翻	`↑ ↓`、`PageUp` / `PageDown`
开始选择 → 复制	`Space` 定起点 → 移动光标选中 → `Enter` 复制
把复制的内容粘回来	`C-b` 然后 `]`
在模式里搜索	`C-s` 向前 / `C-r` 向后（默认 emacs 风格）
退出复制 / 滚动模式	`q`
开鼠标滚轮（直接滚轮翻 + 鼠标选）	执行 `tmux set -g mouse on`，或写进 `~/.tmux.conf`
按住 Shift 用鼠标（绕过 tmux 鼠标模式）	按住 `Shift` 拖动选中文字 → 浏览器右键「复制」；右键「粘贴」

提示：开了 mouse on 后鼠标归 tmux 管;想用浏览器原生的框选 + 右键复制粘贴,按住 Shift 再拖动 / 右键即可。

提示：在 tmuxes 里新建 / 选择 / 重命名 / 杀会话直接点 UI 就行，不用记命令；但往上滚看历史、复制文字、拆面板这些是 tmux 自己的功能，得用上面的快捷键。

❓ 常见问题

某个集群里 tmux 的中文(或其它非 ASCII 字符)全变成了下划线 _?

那台机器的登录 locale 不是 UTF-8(HPC 登录节点很常见,LANG=C / POSIX),于是 tmux 进入非 UTF-8 模式,把每个多字节字符用 _ 占位。在那台机器上修:

设一个 UTF-8 locale —— 先看哪些可用,再写进 ~/.bashrc / ~/.zshrc:

locale -a | grep -i utf          # 看有哪些(C.UTF-8 / en_US.UTF-8 / zh_CN.UTF-8 …)
echo 'export LANG=C.UTF-8' >> ~/.bashrc   # 换成上面真实存在的那个

重启该机器上的 tmux 服务,让会话以 UTF-8 重新创建:
```
tmux kill-server
```
回到 tmuxes 重新连接 / 新建会话即可。

⚠️ pane 的 UTF-8 模式在创建时就定死了 —— 只改 locale 不重启 server 的话,已经变成下划线的旧会话不会自动恢复,必须重建。

📋 更新日志

0.1.12

Codex auto-review 提醒修复：Codex 开启 approvals_reviewer = "auto_review" / Approve for me 时，审批请求会保持 running 状态，不再误触发 决策 badge、提示音或后台标签页闪烁；人工审批配置仍会正常提醒。

0.1.11

文档 / 发布规范：补齐 npm 发布检查流程，明确只发布 server workspace，发布前后都要验证 npx / npm exec 入口和本机启动 smoke test。
安全约束：发布流程不得提交或粘贴 .npmrc token、NPM_TOKEN、SSH 私钥、一次性验证码或任何个人凭据。
README 重整：安装说明加入 npx --help 验证、Windows 排错提示，并压缩早期版本更新。

0.1.10

发布修正：重新发布 npm latest 包，确认线上 tmuxes bin、前端 public 资源和 npx tmuxes@latest 入口可用。

0.1.9

修复: Windows SSH 原生管理命令改用应用层长连接。避免 Windows OpenSSH ControlMaster mux socket 的 getsockname failed: Not a socket，同时避免短命管理命令反复新建 SSH 连接。
改进: 文件浏览器合并远端目录刷新。一次远端调用同时读取 pane 工作目录、校验路径并列目录，减少 SSH 管理流量。

0.1.0 - 0.1.8

早期功能成型：完成本地 / SSH / WSL / Windows shell 目标、tmux attach 多端同步、拖拽文件夹树、工作目录文件浏览与编辑。
agent 提醒演进：从活动转静止提醒升级到 Claude Code / Codex 官方 lifecycle hooks，支持结束、决策和异常停止状态。
Windows / SSH 稳定性：修复 ConPTY 下 Ctrl+C 退出、恢复浏览器原生右键，并将 SSH 管理命令改为长期复用连接且中断后只自动重试一次。

_{用 React、TypeScript、node-pty & xterm.js 打造 —— 外加大量 tmux。盯娃愉快。🤖}

🧑‍🔬 关于作者

嗨，我是这个项目的作者 👋

中国科学技术大学（USTC）理论物理在读博士，白天的日常是和多体场论可解释的费米超流理论（这玩意是用来研究和解释高温超导的），还有一大坨高性能数值计算代码贴身肉搏 ⚛️。

这个小工具其实是被一堆 agent 终端搞到头大之后的「自救产物」—— 既然每天都要盯一群 CLI agent 干活，那干脆给它们造个顺手的指挥台 😎。

如果你也对这些感兴趣（物理也好、代码也好），或者想一起折腾这个开源项目，随时来找我玩 📮

📧 [email protected]