herdr-radar

See every agent at a glance

English · 简体中文 · 日本語

What it is

A Herdr plugin that turns the sidebar's Agents list into something you can read: who is working, who is waiting on you, who has been parked for two hours — without opening each one. It takes effect on install, writes only the display tokens the sidebar shows, and never touches the agents themselves or your pane names.

Why

With a dozen coding agents open, Herdr's own Agents list does not help: every session is a line of the same grey text, done collapses into idle within seconds, and the one asking you a question looks exactly like the one abandoned last Tuesday. You end up switching into each pane to find out.

herdr-radar puts that information on the sidebar: a finished session keeps its tick until you have looked, a question keeps its mark until you answer, sessions that have gone quiet fade, sessions of one project sit under one header, and the busiest project sits on top.

What you get

• State does not slip away. The tick stays until you focus the pane, the question mark stays until the agent works again, idle splits into three tiers by time since the last turn, and abandoned sessions dim as a whole row.
• The list has structure. Workspaces get headers, git worktrees hang under their repository as a tree, the halves of a split screen hang off the pane they came from, the busiest project sorts first, and the Spaces column takes the same colours.
• The surroundings follow. The tab bar shows the current directory, Herdr's theme switches with the desktop's light and dark, and one settings popup holds every option.

Quick start

herdr plugin install hhdebb/herdr-radar

That is the whole install. On its first start the plugin finishes the rest itself: it writes three managed blocks into Herdr's config.toml (fenced by marker comments, nothing outside them is touched), installs the icon font into your user font directory (no admin rights needed), and writes the codepoint map into Ghostty / kitty configs if they exist.

[!IMPORTANT] Herdr starts plugins from its server at startup. If the sidebar has not changed after installing, start the daemon once: herdr plugin action invoke hhdebb.herdr-radar.state-start. Restarting Herdr (herdr server stop, then herdr) works too, but it ends every process in every pane. New terminal windows pick up the font; some terminals need a full restart.

[!NOTE] Requires Herdr 0.9.0+ and Node 18+. Tested on Windows 11 and macOS; Linux not yet. Terminals without a codepoint map (Windows Terminal, iTerm) and the tab bar not following cd on Windows are covered under Troubleshooting.

Two keys, optional — paste into config.toml. Both go through Herdr's prefix (ctrl+b by default), so they cannot collide with anything running inside a pane:

[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "hhdebb.herdr-radar.view-flip"       # order: active <-> recent

[[keys.command]]
key = "prefix+comma"
type = "plugin_action"
command = "hhdebb.herdr-radar.settings"        # settings popup

From a checkout instead of GitHub:

git clone https://github.com/hhdebb/herdr-radar.git
herdr plugin link ./herdr-radar
herdr plugin action invoke hhdebb.herdr-radar.state-start

plugin link runs no build step; the daemon does the same setup on its first start, which is what the third line is for.

Or hand it to an agent

Paste this at a coding agent and it will do the install:

Install the herdr-radar plugin for Herdr on this machine.

1. herdr plugin install hhdebb/herdr-radar
2. herdr plugin action invoke hhdebb.herdr-radar.state-start
3. Check it took: `herdr plugin list` shows hhdebb.herdr-radar as enabled, and
   `herdr agent list` shows a `sort_key` token on the panes that run an agent
   (that one is written whatever state a pane is in; the logo token's name
   changes with the state).

Do NOT run `herdr server stop`, and do not kill the Herdr process. That ends
every program in every pane, including whatever is running you. Nothing here
needs a restart: the plugin configures itself on first start, and new terminal
windows pick up the icon font on their own.

Needs Herdr 0.9.0 or newer and Node 18 or newer. If the marks come out as
boxes, the terminal has no codepoint map for them — that case and the rest are
covered under Troubleshooting at https://github.com/hhdebb/herdr-radar

What the sidebar looks like

dashboard
  ⣟ ✳ Implement OAuth scopes            ← working: braille spinner, title in the vendor's colour
  ✓ ✳ Wire retry budget into dispatcher ← done: green tick, held until you look
  └─  feature/mc-13200                  ← a worktree under its repository
    ? Λ Which env file should I edit?   ← blocked: a pulsing red mark, it is asking you
billing
  ✳ Trace duplicate charges             ← idle: just stopped
  ✳ Migrate invoices table              ← idle for two hours: the whole row dims

One row per agent: logo, title, colour by state, motion and marks in front of the title. Two orders: active keeps the groups and ranks by activity at both levels; recent is a flat list by activity — prefix+a flips between them. The whole panel can be handed back to Herdr's own rendering from the settings popup.

What the colours mean

Two things are worth knowing about a row at a glance, and they are carried separately: the logo says whose agent it is, the title says what that agent is doing. Neither reading depends on the other.

The logo wears the vendor's own colour, and only ever the one the vendor publishes. A brand that signs itself in black or white has no hue to borrow, so its mark is simply drawn in ink — black on a light panel, white on a dark one — rather than in a colour this project invented for it. Nothing about a row's state changes the logo.

The title carries the state, and shape carries it too, so the panel still reads without colour:

Green and red are semantic and outrank branding: they are there to pull the eye, so no vendor colour is allowed to be either. A working title takes its vendor's hue rather than one shared "busy" colour because with thirty rows on screen the hue is what separates one running session from the next before any of them is read.

Idle is a gradient, not a state. Once an agent stops, the only question left is how long ago, so the title cools with the time since its last turn: the first 15 minutes read as just stopped, then plain text out to two hours, after which the whole row dims — logo, marks and all — and sinks to the bottom of its group. Both thresholds are settings (activity_fresh_minutes, activity_stale_minutes). All three tiers draw the same ring, and colour alone says which one: a mark that changed shape as it aged would have to be learned three times.

The Spaces column takes the same vendor colours, so a workspace running Claude and one running Gemini are told apart there too.

Which agents it knows

Twenty-three vendors have a mark of their own:

Herdr detects three more — Droid, Letta and Muse — and none publishes a mark this project can use. Those rows behave like any other — state, colour, orderi