herdr-sdk
A small synchronous client for Herdr's socket API: typed requests, an event stream, and the slice of Herdr's schema that plugins actually touch.
[]
= "0.0.1"
▲ A 0.0.x requirement is exact in Cargo: "0.0.1" resolves only to 0.0.1,
never to 0.0.2. That is the correct reading of where this is — bump it
deliberately.
use ;
let mut client = connect?; // $HERDR_SOCKET_PATH
let panes: PaneList = client.call?;
for pane in panes.panes
Herdr's own answer to "what is the plugin API" is the entire CLI — a plugin is a
manifest plus any argv command, and HERDR_BIN_PATH is the portable way in. This
crate is for the other case: a Rust plugin that would rather speak the socket
directly than shell out per call, and would rather not hand-roll the parts of it
that are surprising.
What it gives you
| Module | What it is |
|---|---|
Client |
One request, one response. Dials per call, because Herdr answers the first request on a connection and then hangs up. |
notify |
Fire-and-forget for callers on a latency budget — an agent hook, where every millisecond blocks a turn. No reply is read, so errors are silent. |
Events |
A held-open events.subscribe that yields frames until Herdr hangs up. |
model |
Pane, Agent, AgentSession, PluginContext and the list wrappers, every nullable field optional and serde(default) throughout. |
cwd |
Where an agent is actually working, and how sure you can be. |
subagents |
The in-process subagents inside one agent, which pane.list structurally cannot see. |
The parts that are surprising
Each of these was measured against a running Herdr, not read from a spec. They are
the reason this crate exists rather than a serde_json::to_writer call at each
site.
- One request per connection. The server answers the first request on a
stream and then sends FIN; a second request on the same socket is never
answered.
Clienttherefore holds a path, not a stream. - Subscribe with dots, receive underscores. You subscribe to
pane.updatedand the frames arrive aspane_updated. Subscribing with the received spelling looks accepted and silently yields nothing, soEventKindowns both spellings and no call site writes either by hand. pane.agent_status_changedis pane-scoped. Subscribing without apane_idis rejected outright.foreground_cwdcannot track a coding agent. It is the OS working directory of the pane's foreground process, and the agents that matter change directory internally without ever callingchdir— omp's/moveand Claude Code's/cdboth do. It stays a source; it must not be the only one, and it must not outrank the agent's own report.cwdresolves that precedence in one place.pane.report_metadatatruncates every string to 80 characters and still answersok. That is whysubagentscarries a roster as a path rather than a payload — a single subject line can exceed 80 characters on its own.
Related
herdr-plugin is an async, tokio-based
application framework for Herdr plugins, with a dispatcher, typed per-domain
clients and plugin state. If you want a framework to build inside, start there.
This crate is the smaller, synchronous option: no runtime, no application shape,
just the socket and the models — which is what a threaded TUI or a one-shot hook
usually wants.
Source
Developed in a private monorepo alongside the plugins that use it, and published
here as a crate. Every source file ships in the published package, so
docs.rs and cargo vendor show the whole thing.
Status
0.0.1 — first published version, extracted from the plugins it was written for.
The surface covers what they need and grows by use rather than by anticipation: a
generated binding for all 89 socket methods would be mostly dead code that still
has to compile. Expect it to move; additions welcome.
MIT.