gtmux 文档gtmux docs

是什么What it is

gtmux 是你 Mac 上 tmux 会话与编码 agent 的指挥中心。它读出你 tmux 里跑的每个 agent，把「谁在等你、谁在干活、谁跑完了」摆成一块雷达；你可以一键跳过去、回它一句，或把盯梢交给一个中控 agent。命令行、菜单栏、手机三处都能用，看到的状态完全一致。免费、开源、MIT。 gtmux is a command center for the tmux sessions and coding agents on your Mac. It reads every agent in your tmux and lays out who’s waiting on you, who’s working, who’s done — as one radar. Jump straight there, reply, or hand the watching to an HQ agent. It works the same from the terminal, the menu bar, and your phone, showing the identical state everywhere. Free, open source, MIT.

安装与首次启动Install & first run

curl -fsSL https://raw.githubusercontent.com/chenchaoyi/gtmux/main/install.sh | bash
gtmux doctor            # health check — then it offers to fix what's missing
gtmux hq                # start the HQ supervisor  (optional)
gtmux serve             # only to connect from your phone or afar

gtmux doctor 先体检，再当场问你要不要把缺的配上——给 Claude Code / Codex / Gemini / aider 装状态 hook（之后它们的等待、完成、报错实时上雷达）、set-titles、重启后恢复、菜单栏 app，每一步都先解释、问过你再动。只想要通知？gtmux install-hooks 只装 hook。菜单栏 app 也可走 Homebrew：brew install --cask chenchaoyi/tap/gtmux-app。 gtmux doctor runs the health check, then offers to set up whatever's missing — state hooks for Claude Code / Codex / Gemini / aider (their waits, finishes, and errors then land on the radar live), set-titles, restore-after-reboot, the menu-bar app — explaining and asking before each change. Just want notifications? gtmux install-hooks does only the hook. The menu-bar app is also a Homebrew cask: brew install --cask chenchaoyi/tap/gtmux-app.

看清并跳过去See it, jump to it

gtmux agents（--watch 是实时仪表盘）把每个 agent 摆成一块雷达，用一套三处一致的状态语言标色：红＝等你、青＝在干活、绿＝空闲/完成、灰＝运行中。「等你」永远只归 waiting——需要你输入的那一类，会排到最上面。看到那个红的，gtmux focus %N 就把那个终端窗口和 pane 带到最前，光标落在 agent 停下的地方。 gtmux agents (--watch is a live dashboard) lays every agent onto one radar in a status language that’s identical across all three surfaces: red = waiting on you, teal = working, green = idle/done, gray = running. “Waiting” is exactly the waiting class — the agents that need your input — and they sort to the top. Spot the red one and gtmux focus %N pulls that terminal window and pane to the front, cursor where the agent left off.

三块屏，同一份状态Three surfaces, one state

• 命令行——gtmux agents --watch 是终端里的雷达，gtmux focus %N 就地跳转。CLI — gtmux agents --watch is the radar in your terminal; gtmux focus %N jumps in place.
• 菜单栏 app——常驻状态点（红/青/绿），弹出面板 + ⌘⌥G 快捷面板；agent 需要你时弹通知，点一下跳过去。Menu-bar app — an always-visible status dot (red/teal/green), a popover + a ⌘⌥G palette; a banner when an agent needs you, click to jump there.
• iOS app——同一套雷达搬到手机：锁屏推送、灵动岛、往 pane 里打字、内置 Demo 免配对先看。iOS app — the same radar on your phone: lock-screen push, Dynamic Island, type into a pane, a built-in Demo to look before pairing.

它怎么知道的？不靠猜——每个 agent 状态一变（停下、完成、报错）就触发一个 hook 写进 gtmux-core，三块屏和推送随即更新。所以它不只支持 Claude：任何装了 gtmux hook 的 agent 都会显示，没装 hook 的就没有信号。gtmux install-hooks 一键给常见 agent 装好。 How does it know? No guessing — each agent fires a hook the moment its state changes (stops, finishes, errors), which writes to gtmux-core, and all three surfaces plus push update. That’s why it isn’t Claude-only: any agent with a gtmux hook shows up; no hook, no signal. gtmux install-hooks wires up the common agents in one shot.

交给中控（参谋长）Hand it to HQ (the chief-of-staff)

agent 多到自己盯不过来时，gtmux hq 起一个常驻的中控 agent。它维护一块态势板（哪怕自己上下文被重置，也记得每个会话在干什么、卡在哪）、一份按轻重分级的事件账本，agent 等你时会被推一下。它不只是转发事件：可逆、低风险、在你已聊过的范围内的事，它自己决定并派发；否则升级给你。你纠正它一次，它会把这条写进自己的章程，下次照做。 When there are too many agents to watch yourself, gtmux hq starts a persistent supervisor agent. It keeps a situation board (it remembers what every session is doing and where it’s stuck, even after its own context is reset), a severity-tagged event ledger, and gets nudged when an agent is waiting. It doesn’t just forward events: reversible, low-risk, in-scope things it decides and dispatches itself; otherwise it escalates to you. Correct it once and it writes that into its own charter, then follows it next time.

中控最具体的能力：派活（spawn / tasks / reap）HQ’s most concrete power: dispatch (spawn / tasks / reap)

gtmux spawn 起一个 agent（新会话 / 指定 pane / worktree）并派给它一个任务，带落地校验（确认任务真的送到了）。gtmux tasks 是派活 / 待你处理的账本。gtmux reap 安全回收一个跑完的派活——worktree 干净、分支已合才回收，否则只报告。中控可以自己派、自己盯、自己收，只在需要你拍板时才来找你。 gtmux spawn launches an agent (a new session, a given pane, or a worktree) and hands it a task with land-verification (it confirms the task actually arrived). gtmux tasks is the dispatch / needs-you ledger. gtmux reap safely reclaims a finished dispatch — only when the worktree is clean and the branch is merged, else it just reports. HQ can dispatch, track, and reclaim on its own, coming to you only when a call is yours to make.

随时接手与分享Access & sharing

先是一道「门」，再决定放谁进来。可达性是一个三档开关——关 / Wi-Fi（gtmux serve）/ 任意网络（gtmux tunnel）；任意网络又分 Standard（零配置、托管、免费）与 Direct（走 443 直连，专为封锁托管边缘的网络准备——访问码解锁，也可自托管到你自己的服务器）。这道门同时管两类人：你自己的设备和协作者——同一条隧道进来。 First a “door”, then who comes through it. Reachability is a three-way switch — Off / Wi-Fi (gtmux serve) / Anywhere (gtmux tunnel); Anywhere is either Standard (zero-config, hosted, free) or Direct (straight over 443, for networks that block the hosted edge — unlocked with an access code, or self-hosted on your own server). The same door governs both kinds of people below — your own devices and collaborators — over one tunnel.

这道门在菜单栏 app 里同样能开：gtmux 图标 → ⚙︎ → 偏好设置… → 远程访问，就是同一个三档开关加隧道后端选择；⚙︎ 菜单的「配对设备…」直接出配对码。不用开终端。 The same door opens from the menu-bar app too: gtmux icon → ⚙︎ → Preferences… → Remote access — the identical three-way switch plus the tunnel-backend choice; “Pair a device…” in the ⚙︎ menu pops the pairing code directly. No terminal needed.

你自己的设备：gtmux pair。它印出一个一次性配对码，三种用法——手机 app 扫二维码、浏览器打开链接、或把那行 gtmux attach 粘到另一台电脑的终端里。配上后无论你在哪个网络都能打开雷达、往 pane 里打字、解开卡住的 agent，不用 VPN；你的设备拥有全部控制权，和坐在 Mac 前一样。 Your own devices: gtmux pair. It prints one one-time code, usable three ways — scan the QR in the phone app, open the link in a browser, or paste the printed gtmux attach line into another computer’s terminal. Once paired, on any network you can open the radar, type into a pane, and unblock a stuck agent, no VPN — your devices have full control, as if you were at the Mac.

要完整终端？在另一台电脑上 gtmux attach <host> %N，把远程某个 pane 的 PTY 桥到你本地终端——原样接着这个会话干，就像坐在 Mac 前。 Want the full terminal? gtmux attach <host> %N from another computer bridges that remote pane’s PTY to your local terminal — pick the session up as-is, as if you were at the Mac.

分享给别人，但攥在自己手里。gtmux share 生成一个受限、可撤销的 guest 链接：默认只读，你按 pane 精确放开「能看」和「能输入」，别人只能碰你允许的会话，绝不等于把整台 Mac 的控制权交出去。看完撤掉，链接立刻失效。 Share with others, keep the reins. gtmux share mints a scoped, revocable guest link: read-only by default, and you open up “can view” and “can type” per pane, so others touch only what you allow — never a handover of your whole Mac. Revoke it when you’re done and the link dies instantly.

命令一览Command reference

最常用的几条：The ones you'll reach for:

gtmux agents [--watch]      # the radar
gtmux focus %N              # jump to a pane
gtmux hq                    # the supervisor
gtmux spawn / tasks / reap  # dispatch a task, track it, reclaim it
gtmux serve / tunnel        # the door: Wi-Fi (serve) / Anywhere (tunnel) — Standard or Direct
gtmux pair                  # enroll YOUR OWN devices: one code, 3 ways (QR / link / attach)
gtmux share                 # a scoped, revocable link for a collaborator
gtmux attach <host> %N      # a remote pane in your local terminal
gtmux devices [revoke <id>] # your paired-device roster (revoke also drops its push)
gtmux doctor                # health check + offers to fix
gtmux update                # self-update CLI + menu-bar app

完整命令、参数与设计说明在仓库里：docs/cli.md · OpenSpec 规格 · README。 The full command set, flags, and design notes live in the repo: docs/cli.md · OpenSpec specs · README.