agent-radar

A self-contained tmux plugin that gives you the one herdr feature worth having
without leaving tmux: see every running coding agent, jump straight to the pane
it lives in, and get told the moment any agent stops needing you, for any
harness, not just the ones with hooks.

What it does

• Detects agent panes: any tmux pane whose foreground process matches the
  allowlist (pi,claude,codex,opencode,hermes,aider,cursor by default).
• Notices when an agent stops: polls each agent pane and looks for the
  harness's live working indicator. A pane is working while that indicator
  is on screen and flips to stopped when it's gone for N seconds.
• Notifies you: an OS notification fires once per stop transition (via osascript on macOS, notify-send on Linux). A tmux window containing an unseen stopped agent stays highlighted until you focus the exact agent pane.
• Shows agent panes at a glance: a tinted second status row labeled 📡 Agent Radar │ displays bracketed panes with red/yellow/green dots (unseen-stopped, working, seen-stopped) and configurable fields. It does not replace your existing first-row status format.
• Navigates: prefix + a opens an fzf popup listing all agent panes,
  stopped ones first, with a red/yellow/green status dot (unseen-stopped,
  running, seen-stopped). Each row is harness, session, window name, :window.pane,
  then the pane's git branch (⎇ <branch>; - when none), separated by ·.
  Harness, session, and window name are bold. The address, the branch glyph, and a
  stopped age are dim. The list refreshes while open. Pick one and it jumps to that
  exact session:window.pane. Example: ● pi · zeta · my-agent-win · :1.0 · ⎇ feat/spam-stop 30s.

Requirements

• tmux
• fzf (for the navigator popup)
• OS notifications use osascript on macOS and notify-send on Linux; if neither is present, the glance row and window highlighting still work. Everything else is cross-platform.

Install

Clone the repo:

git clone https://github.com/vieitesss/agent-radar.git ~/.tmux/plugins/agent-radar

Then add to ~/.tmux.conf. For a one-row baseline and a glance showing only the status dot, session name, and Git branch, put the options before loading the plugin:

set -g status on
set -g @agent-radar-glance-fields 'dot,session,branch'
run-shell ~/.tmux/plugins/agent-radar/agent-radar.tmux

status on gives tmux one row when the glance is off; with the default row setting, agent-radar raises it to two while the glance is on. If you already use custom status rows, keep your chosen base count instead. With TPM, skip the clone and run-shell: put the options before set -g @plugin 'vieitesss/agent-radar', then load TPM as usual with run '~/.tmux/plugins/tpm/tpm'. Do not load the plugin twice. Reload with tmux source-file ~/.tmux.conf.

The glance tint defaults to the theme's @thm_surface_0 when available (for example, Catppuccin), otherwise terminal palette color colour8. To choose a different shade, add set -g @agent-radar-glance-tint '@thm_mantle' before loading the plugin, or use a tmux color such as #303446. Set it to default to inherit the original status background. Palette option names resolve when the row renders, so a theme can load after this setting.

Usage

• prefix + a: open the navigator popup, select an agent, jump to its pane.
• prefix + A: toggle the glance row for the live tmux server. This does not change @agent-radar-glance in your config; sourcing the config restores that setting.
• The default fields dot,target render 📡 Agent Radar │ [● zeta:1.0] [● other:2.1]. The installation example uses dot,session,branch and renders 📡 Agent Radar │ [● karakuri · ⎇ main] [● mentormatic · ⎇ feat/spam-stop]; a missing branch appears as -. Panes are separated by a space, while fields within a pane use · where applicable. The label remains when fewer panes fit on a narrow row.
• Windows containing unseen stopped agents stay highlighted until you focus the exact pane. With the glance off, highlights and seen marks refresh when you switch windows rather than on every status interval. The plugin does not add to status-left.

Options

Set with tmux set-option -g <name> <value> (or set -g in ~/.tmux.conf):

Releasing

To release, create and push an annotated vX.Y.Z tag on main with a message
like Release vX.Y.Z: <summary>. The tag push runs the test suite and, if it
passes, publishes a GitHub release with notes generated from conventional
commits since the previous tag.