herdr-hud

Repository removed. As of 14 October 2026, Dan-Seo/herdr-hud no longer exists on GitHub, so the install commands on this page no longer work. We keep the page as a record of what the mod did and will update it if the author publishes it again.

herdr-hud draws a small read-only list above the Claude Code prompt with every agent running in Herdr: its name, its kind (Claude, Codex, Gemini) and whether it is working, idle, done or blocked. It refreshes every 2 seconds and costs no tokens.

Herdr runs several coding agents side by side in panes and ships a herdr CLI that reports on them. The HUD is only a window into it: without Herdr installed and at least one agent running, the band shows ○ not connected and the reason.

Rows carry a status symbol (● working, ○ idle, ✓ done, ! blocked, ? unknown) and end with + N more when agents outnumber rows.

Since 0.3.0 there is also an opt-in, off by default: two tools that let Claude hand a read-only review of your uncommitted changes to a Codex job running in a Herdr pane the plugin opens for itself, and read the findings back.

Codex delegate (opt-in)

With the delegate option on, the model gets herdr_delegate and herdr_collect. The first snapshots the tracked changes against HEAD, staged and unstaged, writes a review packet outside the repository and queues a job, answering at once with a task id. The second reports the job’s status (queued, starting, running, completed, failed, timed out, needs attention) and, once completed, the findings with file, line, severity and evidence. The HUD gains a DELEGATE row such as review · running · 38s; clicking it focuses the worker pane.

The job runs codex exec --sandbox read-only in a sibling pane the plugin split below your session, through herdr pane run. Files matching .env*, *.pem, *.key, credentials*, secrets* and a few more are left out of the diff, untracked files are named but not sent, and the diff is cut at 200,000 characters. Nothing is committed, stashed or reset; if the tree changes after the snapshot the result is marked stale. One job at a time per session, five reviews per session by default (delegateMaxCalls), ten minutes each (delegateTimeoutMs), and the worker is not killed at the deadline. Every review uses your Codex account. The tool description and every result tell Claude the findings are an external opinion to check, not instructions.

Install

Needs Claude Code 2.1.287 or later, Herdr 0.8.2 or later with the herdr CLI on your PATH, and an interactive terminal. The delegate also needs the Codex CLI on PATH and logged in.

claude plugin marketplace add Dan-Seo/herdr-hud
claude plugin install herdr-hud@herdr-hud

Nothing to start: the band appears when a session begins. Click an agent’s row to bring its pane to the front in Herdr. To turn the delegate on, set delegate to true under pluginConfigs["herdr-hud"].options in your user settings.json or in /config; delegateCodexModel passes a model to codex exec -m.

How it works

On session.start, in interactive terminal sessions only, the module starts a 2 second timer that runs herdr agent list and parses the JSON it prints. It redraws only when the rows would change. The module makes no network calls itself; the herdr CLI talks to Herdr’s socket on its behalf. Nothing is written to disk and nothing reaches the model, so the HUD costs no tokens.

Clicking a row runs herdr agent focus <pane>, with a toast if that fails. A missing CLI, a stopped Herdr or an unexpected answer put the band in not connected instead of failing the session.

With the delegate on, session.start also registers the two tools and a second 2 second timer that drives the job: it splits the worker pane, watches it for an end marker carrying the task id and exit code, then reads the JSON Codex wrote and validates it against an output schema. A tool.call hook answers the two tools; a review cannot be awaited inside the call because a hook has a budget of about 10 seconds. Task files are left under the system temp folder (herdr-hud/<taskId>) for inspection. A session running inside the worker pane registers no delegate tools, so a worker cannot delegate again. The HUD stays free of tokens; with the delegate on, the two tool descriptions sit in the model’s tool list and a review’s findings enter the context when Claude collects them.

Limitations

• Terminal only. Nothing draws in claude -p, the desktop app or mobile.
• Polling, not push. A hooks module cannot open sockets, so the HUD shells out every 2 seconds.
• Six rows minimum. The band never shrinks below six rows, so on a short terminal it takes a large share of the screen.
• One interaction. Clicking a row is all there is; refresh and new-agent buttons are ideas, not features.
• Delegate verified on Windows only. The author ran the full flow on Windows 11 with Claude Code 2.1.272, Herdr 0.8.2 and codex-cli 0.154.0. The macOS and Linux runner script was written but never executed, the HUD rows of a running job were checked only in layout tests, and Codex’s read-only sandbox was not verified on Windows. Local Herdr only.
• Lightly tested edges. Windows was tried only on the author’s machine, and Herdr shutting down under a live session was verified only in the hook tests.