You have five coding agents going at once: one refactoring, one running tests, one writing docs, spread over a dozen tmux windows. What you lose track of is which one has stopped to wait for you. This guide sets up the radar that shows it at a glance.
Run each agent in its own tmux pane
The radar scans tmux panes, so an agent has to run inside tmux to be seen, jumped to and replied to. (Outside tmux, an agent with the gtmux hook is listed read-only.) Start a named tmux session and the agent inside it, one agent per pane. After installing and signing in to the agent CLIs:
tmux new -s api 'claude'Detach with Ctrl-b d, or open another terminal window, before starting the next one:
tmux new -s docs 'codex'Why tmux: its sessions persist. Close the terminal, drop the SSH connection, unplug the
display, and the agent keeps running. Each agent has its own name and pane, so you can
find it and tell it apart. After a reboot, gtmux restore rebuilds the sessions and their
layout from the last saved tmux-resurrect snapshot; the programs come back as new
processes, and by default an agent whose conversation can be recovered picks it up again.
gtmux doctor sets up the saving. Closing a MacBook’s lid still puts the whole machine to
sleep, agents included; gtmux awake on keeps it running with the lid shut. New to tmux?
The official Getting Started covers
what you need.
Put your agents on the radar
Install a hook once for each agent you use. It reports turn and approval state directly; Copilot and Kiro need it to appear on the radar. Some other agents can also be detected from their process and screen:
gtmux install hooks --agent claude
gtmux install hooks --agent codexWithout --agent it sets up Claude Code only. Repeat for the agents you use: gemini,
cursor, opencode, kimi, copilot or kiro. An agent that was already running picks
the hook up after a restart. gtmux doctor --fix offers the hook for Claude Code, and for
Codex and Kimi Code when it finds them; the others need the command above.
For agents with process detection, gtmux can read fallback state without a hook from the pane title, screen and CPU sampling, with less detail (a live Codex approval menu still shows as waiting). Only an agent running outside tmux needs the hook to be seen at all.
Open the radar
gtmux agents --watch # a live dashboard in your terminal; ↑/↓ select, Enter jumpsOr keep it in view: the menu-bar app (installed by the install script, or
brew install --cask chenchaoyi/tap/gtmux-app) shows a status dot, opens a palette with
⌘⌥G, and posts a notification when an agent needs you. The iPhone and iPad app shows the
same radar. See Manage from your phone and the web.
See every tmux pane
To see everything else in tmux too (shells, editors, dev servers), gtmux panes lists
every pane, agent or not. The apps call it All panes.
Jump to the one that is waiting
gtmux focus %7 # bring that pane's window and pane to the frontOr click its row in the menu-bar popover, or the notification. gtmux brings the terminal
window and pane forward with the cursor where the agent stopped; you answer, and it carries
on. Jumping works with Ghostty 1.3+, iTerm2 and cmux, and Warp on a best-effort basis, and
it needs tmux’s set-titles option, which gtmux doctor sets
(gtmux focus).
On the Mac, ⌥⌘4 captures an image for an agent. In the editor, Return adds a new line to the note and ⌘↩ sends. Resizing the window scales the image and its marks together; the exported screenshot keeps its original pixel size.
Next: too many agents to watch yourself? Let HQ watch the fleet for you · Away from the desk? Manage from your phone and the web · Every command: the CLI reference
Source: docs/guides/watch-a-fleet.md at v1.0.114 · Edit on GitHub
你同时开着五个 coding agent：一个在重构，一个在跑测试，一个在写文档，散在十几个 tmux 窗口里。最容易丢的，是哪一个停下来在等你。这篇把雷达搭起来，让你一眼看出来。
每个 agent 跑在自己的 tmux pane 里
雷达扫的是 tmux pane，agent 得跑在 tmux 里才看得到、跳得过去、回得了话。（tmux 之外的 agent 装了 gtmux hook 也能看到，但只读。）先开一个有名字的 tmux 会话，再在里面启动 agent，一个 agent 一个 pane。装好并登录 agent CLI 后：
tmux new -s api 'claude'按 Ctrl-b d 脱离这个会话，或者另开一个终端窗口，再起下一个：
tmux new -s docs 'codex'为什么用 tmux：它的会话是持久的。终端关了、SSH 断了、显示器拔了，agent 都还在跑；每个 agent 有自己的名字和 pane，找得到也认得出。重启后，gtmux restore 从最近保存的 tmux-resurrect 快照重建会话和布局，程序是重新起的进程；默认情况下，能恢复对话的 agent 会接着原来的对话。保存机制由 gtmux doctor 配好。MacBook 合盖仍会让整机休眠，agent 也跟着停；gtmux awake on 让它合盖后继续跑。没用过 tmux？官方的 Getting Started 够用了。
让 agent 上雷达
每种使用的 agent 安装一次 hook，直接报告回合和审批状态。Copilot 和 Kiro 需要 hook 才能出现在雷达上；部分其他 agent 也能从进程和屏幕识别：
gtmux install hooks --agent claude
gtmux install hooks --agent codex不加 --agent 只配 Claude Code。你用哪些就接着配哪些：gemini、cursor、opencode、kimi、copilot 或 kiro。已经在跑的 agent 重启后才会用上 hook。gtmux doctor --fix 会主动提出给 Claude Code 配 hook，找到 Codex 和 Kimi Code 时也会；其余的要用上面那条命令。
支持进程识别的 agent 不装 hook 时，gtmux 从 pane 标题、屏幕和 CPU 采样读取回退状态，细节少一些（Codex 正在弹的审批菜单仍会显示为等待）。只有跑在 tmux 外面的 agent 必须装 hook 才看得到。
打开雷达
gtmux agents --watch # 终端里的实时看板；↑/↓ 选择，回车跳过去或者让它常驻：菜单栏 app（安装脚本会一起装，也可以 brew install --cask chenchaoyi/tap/gtmux-app）在菜单栏放一个状态点，⌘⌥G 唤出面板，有 agent 等你时发通知。iPhone 和 iPad app 上是同一块雷达，见用手机和网页远程管理。
查看所有 pane
想连 tmux 里其他东西也看到（shell、编辑器、开发服务器），gtmux panes 会列出每一个 pane，不管是不是 agent。app 里它叫「所有 pane」。
跳到在等你的那个
gtmux focus %7 # 把那个 pane 所在的窗口和 pane 带到最前或者点菜单栏面板里那一行，或者点通知。gtmux 把终端窗口和 pane 带到前面，光标就在 agent 停下的地方；你回一句，它接着干。跳转支持 Ghostty 1.3+、iTerm2 和 cmux，Warp 尽力支持，还需要 tmux 的 set-titles 选项，gtmux doctor 会帮你设好（gtmux focus）。
Mac 上按 ⌥⌘4 可截图发给 agent。编辑页的附言框支持回车换行，⌘↩发送；调整窗口时，截图和标注一起等比缩放，导出仍保留原始像素尺寸。
接下来：agent 多到自己盯不过来？让 HQ 替你盯全局 · 不在电脑前？用手机和网页远程管理 · 全部命令：CLI 参考
来源：docs/guides/watch-a-fleet.zh.md（v1.0.114）· 在 GitHub 上编辑