Herdr Cockpit is a local supervision plugin for Herdr that shows what every coding agent is doing, lets me search their work, and reminds me when an agent finishes.
Herdr already runs coding agents in parallel across panes. The daily tax is everything around that: opening every pane to see who is working, blocked, or done; forgetting which session handled what; and checking again to learn whether a task finished.
Cockpit removes that loop. One popup shows every agent, what it is working on, how long the current turn has been running, and total working time. Search finds sessions by their work. A voice or text reminder brings you back on completion. Focus modes protect your attention while agents run. One keypress jumps to the agent that needs you.
Full guide: docs/COCKPIT.md (architecture, protocols, data model, operations).
| Herdr provides | Cockpit adds |
|---|---|
| Workspaces, tabs, panes, splits, focus | Aggregated live supervision dashboard |
| Coding-agent detection and lifecycle | Restart-safe current and cumulative timers |
| Agents sidebar | Summary and elapsed metadata published into that sidebar |
| Plugin install, panes, and actions | Selected-agent handoffs to installed plugins |
| Socket/API access to panes and agents | Session memory: bounded sanitized excerpts, FTS, optional embeddings |
| Notifications | Completion-reminder state machine (voice + text) |
| Navigation between agent panes | Observe / guarded / committed focus sessions (macOS) |
Cockpit does not run agents, own the pane system, or reimplement browser/file/review/PR/usage UIs. Those stay upstream Herdr plugins. Cockpit focuses the selected agent, then invokes a static compatibility table of known plugin actions after a live install check.
Cockpit is the new supervision layer in this composition. The Cockpit repository contains the daemon, popup TUI, timers, session search and sanitization, reminder state machine, focus integration, CLI, agent skill extensions, and the compatibility layer that focuses an agent before opening an installed Herdr tool.
The underlying Herdr platform already provides workspaces, panes, agent lifecycle detection, plugin actions, the sidebar shell, and notification transport. Cockpit does not claim those as its own implementation.
Cockpit's curated companion stack uses these separate repositories:
| Existing component | Repository | Cockpit's role |
|---|---|---|
| Browser | ogulcancelik/herdr-browser | Open the installed Browser pane |
| Files | smarzban/herdr-file-viewer | Open the installed file viewer |
| Review | persiyanov/herdr-reviewr | Open the installed diff-review tool |
| PR | wyattjoh/herdr-plugin-gh-pr | Open the installed PR/CI status tool |
| Usage | senna-lang/herdr-agent-usage | Open the installed usage meter |
| Clipboard/URLs | rmarganti/herdr-pluck | Curated companion, not reimplemented by Cockpit |
These tools remain upstream plugins. Cockpit composes them through a pinned stack and static compatibility table; it does not vendor, fork, or own their UI. The base platform is herdrdev/herdr.
Open the popup (prefix+shift+C). See status, current-run duration, total working time, and a short "working on" line per agent. Enter jumps to that pane. Timers are derived from absolute timestamps in SQLite, so sleep and daemon restarts do not drift the clocks.
cockpit sessions # CLI table
cockpit sessions --json # scripts and agents
cockpit doctor # connectivity checkBounded pane.read ingestion (200 lines, 12KB cap) is sanitized before storage (AWS/GitHub/OpenAI/Slack tokens, Bearer, key=value secrets). Lexical search uses SQLite FTS5. Optional hybrid/semantic search embeds the query and fuses ranks with Reciprocal Rank Fusion when a model endpoint is configured.
cockpit search cargo websocket
cockpit search --semantic "clipboard support"In the popup: / lexical · Ctrl+S semantic rerank. If the model endpoint is down, lexical results still work.
While an agent works, record a short voice note (r in the popup, or prefix+shift+R for the current pane) or arm text from anywhere:
cockpit remind <agent> --text "Review ownership cleanup"Arming semantics (no turn IDs in Herdr): armed while working fires on the next working→idle/done; armed otherwise waits a full work cycle; working→blocked never fires; pane close or agent replacement cancels. Delivery is at-most-once: the row is marked delivered before side effects, so a crash mid-delivery will not retry (you may miss a toast, you will not get a duplicate attempt). Recordings are deleted after delivery or cancel.
cockpit focus start --minutes 45
cockpit focus start --mode guarded --minutes 45 --allow com.apple.Safari
cockpit focus start --mode committed --minutes 90
cockpit focus stop # refused in committed mode
cockpit focus escape # friction exit for committedObserve nudges when you leave the target app. Guarded warns, counts down, and returns you to the exact target (bundle ID + PID). Committed is guarded plus no ordinary stop: escape needs a generated phrase, cooldown, and reason. Deadlines are absolute and release even if the daemon dies. Enforcement is cooperative only (Force Quit always works). Website blocking is recorded for a future integration and is not enforced.
cockpit stack install --group core
cockpit with review pi # focus pi, open reviewr
cockpit with files # file viewer for current contextPopup keys: b browser · v files · d diff review · u usage · p PR. Compatibility is a static table of known plugin/action IDs plus a runtime "is this plugin installed?" check, not live action discovery.
| Capability | macOS | Linux |
|---|---|---|
| Daemon, timers, popup TUI, CLI | yes | yes |
| Lexical search + sanitization | yes | yes |
| Summaries / semantic search (configured model endpoint) | yes | yes |
Text reminders + Herdr notification.show |
yes | yes |
| Voice record + playback | ffmpeg/avfoundation; afplay / say |
SoX rec; Herdr text notification (desktop playback is macOS-oriented) |
macOS toast via osascript |
yes | no |
| Focus modes (companion frontmost/activate) | yes (cockpit-companion) |
no (companion is macOS-only) |
Stack integrations (cockpit with …) |
yes | yes |
Agent skill (skills/herdr) |
yes | yes |
State is local: one SQLite database and an owner-only Unix socket under the plugin state dir (~/.local/state/herdr-cockpit by default). No network listeners.
Optional model calls (summaries, embeddings, semantic query) go to the configured OpenAI-compatible endpoint (COCKPIT_LLM_BASE, default http://localhost:1234/v1). Remote endpoints must use HTTPS. Summary requests include the agent kind, project directory, and bounded sanitized excerpt; embedding requests include a generated summary card or the search query. Model failure never affects timers or lexical search.
- Herdr ≥ 0.7.5
- Rust toolchain
- macOS or Linux (see platform matrix)
- Optional, for summaries/semantic search: an unauthenticated OpenAI-compatible server
- defaults:
COCKPIT_LLM_BASE=http://localhost:1234/v1 - summary:
qwen/qwen3.6-35b-a3b(reasoning disabled via API) - embedding:
text-embedding-qwen3-embedding-8b
- defaults:
git clone https://github.com/WyvernMonarch/herdr-cockpit.git && cd herdr-cockpit
./install.sh # build, link plugin + ~/.local/bin/cockpit, start daemonThen:
herdr plugin pane open --plugin cockpit.core --entrypoint cockpit # the popup
cockpit sessions
cockpit doctorIf ~/.local/bin is not already on PATH, the installer prints the exact
directory to add. Override the CLI destination with COCKPIT_BIN_DIR.
Merge config/keys.example.toml (prefix = ctrl+b by default):
| Key | Action |
|---|---|
prefix+shift+C |
open the Cockpit popup |
prefix+shift+S |
popup straight into search mode |
prefix+shift+R |
voice reminder for the agent in the current pane |
prefix+shift+F |
toggle a 25m focus session (macOS; notification feedback) |
Inside the popup: / search · Ctrl+S semantic · Enter focus agent · r record reminder · f focus chooser · F stop focus · q close.
cp config/cockpit.env.example "$(herdr plugin config-dir cockpit.core)/cockpit.env"
$EDITOR "$(herdr plugin config-dir cockpit.core)/cockpit.env" # COCKPIT_LLM_BASE / _SUMMARY_MODEL / _EMBED_MODEL
cockpit daemon stop && cockpit daemon ensurejust dev # debug build staged into the plugin
just bounce # rebuild + restart daemon
just open # open the popup in the focused session
just test # domain tests (cargo test)herdr (socket API)
▲ ▲
│ │ one-shot JSON calls (agent.list, agent.focus, ...)
│ └──────────────┐
│ events.subscribe │ IPC (owner-only unix socket)
│ (pane lifecycle) │ ┌──────────────────────────┐
┌──┴───────────────────────┴──┐ │ cockpit ui (popup TUI) │
│ cockpit daemon │◄────┤ cockpit sessions/focus │
│ · reconcile + timers │ │ plugin actions │
│ · SQLite (sessions, │ └──────────────────────────┘
│ status_intervals, …) │
│ · self-ensuring lifecycle │
└─────────────────────────────┘
- One binary, one plugin. Startup hook runs
daemon ensure; the daemon is self-ensuring because Herdr startup hooks are one-shot. - Timers are derived, never counters. Status transitions persist as absolute-timestamp intervals; every displayed duration is computed at read time.
- One-request-per-connection. Herdr's socket closes after each response (subscriptions excepted). Status changes arrive via the 1.5s reconcile tick plus lifecycle events.
- Third-party plugins stay upstream.
stack.tomlcurates the companion stack;cockpit stack installdrivesherdr plugin install.
skills/herdr/SKILL.md is the upstream Herdr skill plus marked Cockpit sections. Agents learn to inspect cockpit sessions, self-report $summary metadata, report native session IDs, and leave human surfaces (reminders, focus) alone. Install with npx skills add <repo> --skill herdr -g or copy the file into your agent's skill directory. Re-sync against upstream with just sync-skill (sections between COCKPIT:BEGIN/END markers are preserved).
plugins/cockpit/ herdr-plugin.toml + staged binary
crates/cockpit/ the cockpit binary (daemon, TUI, CLI, stack)
crates/cockpit-core/ herdr client, IPC, store, timers
skills/herdr/ modified agent skill
stack.toml curated third-party plugin stack
config/ recommended sidebar rows + keybindings (opt-in)
artifacts/ research and presentation handoffs
docs/ full guide (COCKPIT.md)