These notes were established against Herdr 0.9.5, socket protocol 22. The sources, most trusted first:
- the live server;
- Herdr's source at
v0.9.5; herdr api schema --json.
When Herdr changes, re-run herdr api schema --json and herdr-scope doctor.
The transport is newline-delimited JSON over $HERDR_SOCKET_PATH: a Unix socket, or the
named pipe \\.\pipe\<path> on Windows.
- A request is
{id, method, params}. The answer is{id, result: {type, …}}or{id, error: {code, message}}. An event is{event, data}, with no id. - The server answers one request per connection, then closes it.
events.subscribeis the only long-lived connection, and the client must not write to it after the request. - Scope uses
github.com/cyperx84/herdr-apifor transport only. ItsAgenttype lackstokens,terminal_id,agent_session,display_agentandtitle, so Scope decodes its own DTOs (internal/adapters/herdr/wire.go).
| Method | Used for |
|---|---|
ping |
protocol gate, version, liveness |
session.snapshot |
the authoritative state: workspaces with worktree info, tabs, panes, agents, focus |
agent.list |
the per-frame refresh of status, title and focus |
events.subscribe |
wake hints |
pane.report_metadata, workspace.report_metadata |
write and clear tokens |
agent.view.set / clear |
the Agents panel's sort and filter |
workspace.move_block |
reorder_workspaces, nest_folders |
pane.list, workspace.list, tab.list |
orphan sweeps, a stop's clear, the tab-bar line |
pane.focus |
the jump action |
pane.process_info, pane.layout |
the tab-bar line: cwd and width |
tab.rename |
mark_tabs; tab_not_found counts as done |
The CLI ($HERDR_BIN_PATH) handles the cold paths: server reload-config, config check,
notification show, plugin pane open and --version. Nothing polls it.
- Agent statuses are
idle,working,blocked,doneandunknown. A hook status (screen_detection_skipped = true) is authoritative. A screen-pattern status can flap toidlemid-turn, anddonecollapses intoidlewithin seconds. - Panes and agents come in layout order. A tab's first pane is the one the others were split from.
- Pane and tab ids restart with every server. A pane moved to another workspace gets a new
id but keeps its
terminal_id, and Herdr still resolves the old id to it. agent_session.valueis the agent's own session id. It survives a Herdr restart when Herdr resumes the agent.- Worktree info does not come from the cwd. A workspace created with
--cwd <checkout>reportsworktree: nulluntil Herdr's own worktree commands touch the repository. Scope's git adapter fills the gap, keyed the same way (repo_key= the git common dir). - Title fields are
string|null, and an empty title arrives as"".
Scope subscribes to lifecycle kinds only:
pane.created pane.closed pane.exited pane.agent_detected pane.focused pane.moved
workspace.created workspace.closed workspace.renamed workspace.focused
tab.created tab.closed tab.renamed tab.moved
(+ workspace.moved workspace.reordered when Scope moves workspaces)
- One bad entry rejects the whole subscription.
- Per-pane subscriptions need a live
pane_id, and each one costs the server apane_getevery 100 ms. Scope readsagent.listonce a second instead. pane.updatedis mostly the echo of Scope's own writes. Subscribing to it was measured to slow every token write from 1–2 ms to about 110 ms.- A burst arrives grouped by kind, not in time order.
- 0.9.5 replays no history. 0.8.x replayed up to 512 events. A subscriber that falls behind
gets
events_lost.
None of this matters for correctness, because an event never changes state. It marks the model dirty, and the next frame reads the authoritative snapshot.
| Limit | Value |
|---|---|
| tokens per request | 16; a larger patch is rejected whole |
| tokens per pane or workspace | 32 |
| key | ^[A-Za-z0-9_-]{1,32}$ |
| value | trimmed, control characters removed, 80 chars max; empty clears |
| source | ^[A-Za-z0-9:._-]{1,80}$ |
null clears a token. Indentation rides on a leading U+200B, which trim() keeps. A report
to a target that is gone (pane_not_found, workspace_not_found) counts as landed. Every
write carries source = "plugin:killallgit.herdr-scope", so Scope's clears cannot touch
another plugin's token.
From [ui.sidebar.agents] in config.toml, as of 0.9.5 (ui/sidebar/tokens.rs):
- A row allows 16 tokens; one more fails the whole config file, and every plugin and keybinding goes down with it. A layout allows 16 rows.
- Visible cells are joined with
·(one space afterstate_icon). Nothing changes that, so a line without the dot is a line of one cell. fgtakes only#RGBor#RRGGBB.rows_by_agent.<id>must name an id Herdr knows, or the file fails to parse.- Spaces indents only worktree families. Any other nesting is the plugin's to draw.
- The focused agent's whole entry, header included, gets
active_row_bg. - The sidebar's background is the terminal's (
sidebar_bgisReset), so rows must be written for the theme's side, not the desktop's. A plugin cannot learn the host terminal: no API returns its colours, and the server has noTERM_PROGRAM.
agent.view.set {source, label, sort, filter} reorders and filters the Agents panel.
{"context": "current_workspace_id"}follows the focus, but only against the built-inworkspace_id.- Folds filter on a token:
not exists folded. - Herdr reports no sidebar clicks. A click on an entry focuses its pane.
- The override lives in server memory and is lost on a restart or live handoff. While it is set, Herdr disables the panel's own toggle.
- Commands run with the plugin directory as cwd.
bin/herdr-scoperesolves against the plugin root. - Herdr injects
HERDR_SOCKET_PATH,HERDR_BIN_PATH,HERDR_PLUGIN_ID,HERDR_PLUGIN_ROOT,HERDR_PLUGIN_CONFIG_DIR,HERDR_PLUGIN_STATE_DIR,HERDR_PLUGIN_EVENT(_JSON)and others. [[build]]runs onplugin install, not onplugin link.[[startup]]runs after the session is restored and after a live handoff.- Action ids may not contain dots.
herdr-scope run refuses protocols below 22, with Herdr Scope requires Herdr protocol 22+.
It accepts newer ones, and doctor warns when the live protocol differs from the tested one.