Herdr Plugin Development
Herdr is a Rust terminal workspace manager for AI coding agents: workspaces, tabs, panes, and per-pane agent lifecycle state (idle, working, blocked, done) in one TUI. The plugin system turns that surface into an extensible platform without an SDK. Herdr stays lean; plugins carry the workflows.
A plugin is a directory with a herdr-plugin.toml manifest plus the argv commands the manifest declares. Herdr validates the manifest, launches your commands on events, actions, keybindings, and pane opens, and injects runtime context through HERDR_* environment variables and JSON payloads. There is no restricted plugin API: the entire herdr CLI is the API. Your commands call back through HERDR_BIN_PATH or the socket like any other client.
- Herdr owns the host surface: installation, manifest validation, keybindings, panes, events, invocation context, and logs.
- Your plugin owns its language, dependencies, files, and durable state.
- Distribution is git-native: a public GitHub repo tagged
herdr-pluginis auto-indexed by the marketplace.
Two archetypes
Ecosystem plugins converge on two shapes, plus a thin-launcher variant.
| Archetype | Trigger | Typical stack | Example |
|---|---|---|---|
| Event/data | [[events]] hooks, [[actions]] | Rust with clap, serde, ureq, rusqlite; or bash+jq; or bun | herdr-agent-usage, herdr-pane-topic-sync |
| TUI pane | [[panes]] entrypoints | ratatui + crossterm + ansi-to-tui | herdr-file-viewer |
| Thin launcher | [[actions]] that exec a real app | shell shim + any language | collie |
Event/data plugins react to the 22 hookable events and call back into the CLI. TUI pane plugins open real terminal panes (overlay, popup, split, tab, zoomed) running full-screen apps. See plugin archetypes.
The lab plugin suite
This topic serves peteretelej/herdr-plugins, the lab’s plugin suite: a Rust cargo workspace with MIT-licensed plugins under plugins/*, using peteretelej.<name> ids (the username-prefixed style with zero collisions in the marketplace index). The quickstart builds the suite’s minimal shape; distribution and versioning covers shipping.
After notable herdr releases, re-verify version-sensitive details against the docs and refresh the local mirrors; notes/maintenance.md owns that loop.
Contents
Concepts
- The plugin manifest -
herdr-plugin.tomlfields, six sections, id rules, platform gating - The event model - hookable events, payloads, delivery semantics, invocation context
- The runtime environment -
HERDR_*variables, config/state/root directories, startup hooks - Plugin archetypes - event/data, TUI pane, thin launcher; dependency stacks and language trade-offs
- The agent state model - agent states, status authority, rollups, automation semantics
- Distribution and versioning - install vs link,
[[build]], marketplace indexing,min_herdr_versiondoctrine
Quickstart
- First Rust plugin - a working event + action plugin with the link/reload/log dev loop