gtmux 文档gtmux docs

是什么What it is

gtmux 是你 Mac 上 tmux 会话与编码 agent 的指挥中心。它读出你 tmux 里跑的每个 agent，把「谁在等你、谁在干活、谁跑完了」摆成一块雷达；再让你一键跳过去、回一句、或交给一个中控替你盯着。一个 Go 核心（gtmux-core），三块屏：命令行、macOS 菜单栏 app、iOS app。免费、开源、MIT。 gtmux is a command center for the tmux sessions and coding agents on your Mac. It reads every agent running in your tmux and lays out who's waiting on you, who's working, who's done — as one radar — then lets you jump there, reply, or hand it to a supervisor that watches for you. One Go core (gtmux-core), three surfaces: the CLI, the macOS menu-bar app, and the iOS app. Free, open source, MIT.

安装与首启Install & first run

curl -fsSL https://raw.githubusercontent.com/chenchaoyi/gtmux/main/install.sh | bash
gtmux install-hooks     # put your agents on the radar
gtmux hq                # start the HQ supervisor  (optional)
gtmux serve             # only to connect from your phone or afar

install-hooks 给 Claude Code / Codex / Gemini / aider 等装上状态 hook——之后它们的等待、完成、报错都会实时上雷达。菜单栏 app 走 Homebrew：brew install --cask chenchaoyi/tap/gtmux-app。 install-hooks wires state hooks into Claude Code / Codex / Gemini / aider — after that, their waits, finishes, and errors land on the radar live. The menu-bar app is a Homebrew cask: brew install --cask chenchaoyi/tap/gtmux-app.

雷达与状态语言Radar & status language

gtmux agents（--watch 是实时仪表盘）列出每个 agent，用一套三处一致的状态语言标色：红＝等你、青＝在干活、绿＝空闲/完成、灰＝运行中。「等你」永远只归 waiting——需要你输入的那一类，会排到最上面。装了 hook 但不在 tmux 里的原生会话也感知得到（只读）。 gtmux agents (--watch is a live dashboard) lists every agent in one status language, identical across all three surfaces: red = waiting on you, teal = working, green = idle/done, gray = running. "Waiting" means exactly the waiting class — the agents that need your input — and they sort to the top. Non-tmux sessions with a hook are sensed too, read-only.

三块屏Three surfaces

• 命令行——gtmux agents --watch 是终端里的雷达；gtmux focus %N 跳到某个 pane。CLI — gtmux agents --watch is the radar in your terminal; gtmux focus %N jumps to a pane.
• 菜单栏 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.

中控 HQ（参谋长）HQ — the supervisor

gtmux hq 起一个常驻的中控 agent（参谋长）。它维护一块态势板（跨上下文重置存活）、一份按重要性分级的事件账本，agent 等你时会去推它。它不只是转发事件：可逆、低风险、在已聊范围内的事它自己决定并派发，否则升级给你。gtmux digest 是它背后那份零 LLM token 的确定性摘要（goal / last / ask）。 gtmux hq starts a persistent supervisor agent — a chief-of-staff. It keeps a situation board (survives context resets), 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. gtmux digest is the deterministic, zero-LLM-token summary (goal / last / ask) underneath it.

派活（spawn / tasks / reap）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.

远程连接Remote access

gtmux serve 在你 Mac 上开一个只读远程雷达（手机 app 连它）；gtmux tunnel 给你一个「从任何网络都能连」的公网地址，不用 VPN。gtmux attach <host> %N 把远程某个 pane 的 PTY 桥到你本地终端——在另一台电脑的终端里，原样接着这个会话干。gtmux share 生成受限、可撤销的 guest 链接，别人只能看/操控你允许的会话。 gtmux serve opens a read-only remote radar on your Mac (the phone app connects to it); gtmux tunnel gives you a "from any network" public URL, no VPN. gtmux attach <host> %N bridges a remote pane's PTY to your local terminal — pick the session up, as-is, from another computer's terminal. gtmux share mints a scoped, revocable guest link so others see or type into only what you allow.

检测与 hookDetection & hooks

gtmux 不靠猜——每个 agent 在状态变化（停下、完成、报错）时触发一个 hook，写进 gtmux-core，三块屏和推送随即更新。这也是它不只支持 Claude 的原因：任何装了 gtmux hook 的 agent 都会显示；没装 hook 的就没有信号。gtmux install-hooks 一键给常见 agent 装好。 gtmux doesn't guess — each agent fires a hook when 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 that installs a gtmux hook shows up; no hook, no signal. gtmux install-hooks wires up the common agents in one shot.

命令一览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        # remote radar + a public URL
gtmux attach <host> %N      # a remote pane in your local terminal
gtmux share                 # a scoped, revocable guest link
gtmux doctor                # check your setup
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.