Skip to main content

Herdr

@magistr/herdrv2026.10.25.10· MIT· 27d agoBEHAVIORS
01README

Drive a herdr terminal-agent runtime from swamp.

herdr (https://herdr.dev) is a terminal multiplexer built for AI coding agents: a background server owns persistent workspaces → tabs → panes, recognises the agent running inside each pane, and exposes the whole tree over a local Unix socket. This model turns that fleet into swamp data and swamp methods.

Model:

  • @magistr/herdr — one instance per herdr server: the local one (default session, a named session, or an explicit socket path), or a server on another host reached over ssh by setting sshHost. The transport is the only difference — every method below works identically against either.

    Observe:

    • status — client/server versions, protocol compatibility, socket in use and the named-session inventory. A stopped server is reported, not thrown.
    • snapshot — the whole session in ONE socket round-trip: a fleet roll-up (workspaces, tabs, pane count, per-state agent histogram) plus one agent resource per agent. Filter by workspace id/label and by agent state.
    • read — capture a pane's or agent's output (visible screen, scrollback tail, or the agent classifier's own detection buffer), bounded by maxOutputBytes and tagged with its pane/tab/workspace.

    Drive:

    • prompt — submit a prompt to many agents in one run, optionally waiting for each to settle.
    • wait-agent — block until agents reach a state (idle/blocked/done).
    • start-agent — launch an agent of a given kind in a pane.
    • send-keys / send-text / run-command — key presses, literal text, and submitted shell commands, fanned out across panes.
    • wait-output — block until a pane's output matches a string or regex.

    Shape:

    • create-workspace, create-tab, split-pane, create-worktree, close, notify.

    Server and sessions:

    • server-stop, server-reload-config (validates config.toml first), server-live-handoff, session-stop, session-delete.
    • agent-manifests, update-agent-manifests (reports exactly which agents moved), reload-agent-manifests.

Idempotent by construction: every mutating method reads herdr's state first. close on a missing id is a recorded no-op; create-workspace, create-tab and create-worktree reuse an existing container with the same label/branch; start-agent leaves a pane that already hosts an agent running. Re-running any method is safe.

Safe to run from inside the fleet it manages: swamp normally executes in a herdr pane, so the model reads herdr's own HERDR_PANE_ID / HERDR_TAB_ID / HERDR_WORKSPACE_ID to refuse to close the terminal issuing the command and to skip the caller when a prompt fans out (an agent prompting itself would wait on its own turn forever).

Transport is the herdr CLI over Deno.Command — never a shell — so every label, prompt and command travels as one literal argv element. Ids and key names that would be read as flags are refused before anything is sent. Over ssh a remote shell is unavoidable, so every argument is POSIX-quoted and the quoting is proved against a real /bin/sh in the property suite.

02Release Notes

2026.10.25.10

  • Repo-wide republish; no functional change.
03Behaviors1
@magistr/herdrv2026.10.25.10extensions/models/herdr.ts
fn status()
Health check: client and server versions, protocol compatibility, the socket in use and every named session. Works whether or not a server is running — a stopped server reports serverRunning false instead of failing.
fn snapshot()
Read the entire herdr session in one socket round-trip and write a fleet roll-up plus one agent resource per agent. The fan-out read: use this instead of looping per-workspace calls. Filter by workspace (id or label) and by agent state.
fn read(target: string)
Capture what a pane or agent is showing — the visible screen, the scrollback tail, or (agents only) the classifier's own detection buffer. Text is bounded by maxOutputBytes and tagged with the pane/tab/workspace it came from.
ArgumentTypeDescription
targetstringPane id (w1:p4) or agent name
fn prompt(text: string)
Submit a prompt to one or many agents in a single run. Optionally waits for each agent to settle. The pane running this method is skipped by default, because an agent that prompts itself waits on its own turn forever.
ArgumentTypeDescription
textstringPrompt to submit to each agent
fn wait-agent(targets: array, failFast?: boolean)
Block until agents reach one of the given states (default idle). Read-only: it observes state transitions and never changes them. Fans out over every target in one run.
ArgumentTypeDescription
targetsarrayPane ids or agent names
failFast?booleanAbort on the first failure
fn start-agent(pane: string)
Launch an agent of the given kind in a pane. Idempotent: a pane that already hosts an agent is left running and its current state is recorded instead, unless force is set.
ArgumentTypeDescription
panestringPane to start the agent in (w1:p4)
fn send-keys(targets: array, failFast?: boolean)
Deliver key presses (enter, esc, ctrl+c, shift+tab, f1, …) to panes or named agents. Use this rather than send-text for control keys and for submitting input.
ArgumentTypeDescription
targetsarrayPane ids or agent names
failFast?booleanAbort on the first failure
fn send-text(targets: array, failFast?: boolean)
Type literal text into panes without submitting it — the text lands at the cursor and Enter is not sent. Use run-command to type and submit in one step.
ArgumentTypeDescription
targetsarrayPane ids
failFast?booleanAbort on the first failure
fn run-command(targets: array, failFast?: boolean)
Type a shell command into panes and submit it with Enter. Fans out over targets so one call drives a whole row of panes.
ArgumentTypeDescription
targetsarrayPane ids
failFast?booleanAbort on the first failure
fn wait-output(pane: string, match?: string, regex?: string)
Block until a pane's output matches a literal string or a regex, then write the matching capture. The building block for 'run something, then continue when it prints X'.
ArgumentTypeDescription
panestringPane id to watch
match?stringLiteral substring to wait for
regex?stringRegex to wait for (instead of match)
fn create-workspace(label: string, cwd?: string, focus?: boolean)
Create a labelled workspace. Idempotent by label: an existing workspace with the same label is returned untouched (created false) unless reuse is disabled.
ArgumentTypeDescription
labelstringWorkspace label — also the reuse key
cwd?stringWorking directory for the first pane
focus?booleanFocus the workspace afterwards
fn create-tab(label: string, cwd?: string, env?: array, focus?: boolean)
Create a labelled tab in a workspace. Idempotent by label within that workspace: an existing tab is returned untouched (created false) unless reuse is disabled.
ArgumentTypeDescription
labelstringTab label — also the reuse key
cwd?stringWorking directory for the tab's pane
env?arrayKEY=VALUE pairs for the pane
focus?booleanFocus the tab afterwards
fn split-pane(pane: string, cwd?: string, env?: array, focus?: boolean)
Split a pane right or down, optionally with a size ratio, cwd and environment. Verifies the pane exists first. Not idempotent by nature — each call adds a pane.
ArgumentTypeDescription
panestringPane to split
cwd?stringWorking directory for the new pane
env?arrayKEY=VALUE pairs for the pane
focus?booleanFocus the new pane
fn create-worktree(branch?: string, base?: string, label?: string, focus?: boolean)
Cut a Git worktree and open it in its own workspace — the isolated-branch primitive for parallel agents. Idempotent: an existing worktree for the branch is opened (or reported already-open) rather than recreated.
ArgumentTypeDescription
branch?stringBranch to check out — the reuse key
base?stringBase ref for a new branch
label?stringLabel for the worktree's workspace
focus?booleanFocus the new workspace
fn close(id: string)
Close a workspace, tab or pane. Reads the live list first: an id that is already gone is a recorded no-op, not an error. Refuses to close the pane/tab/workspace running this method unless force is set.
ArgumentTypeDescription
idstringContainer id: w1, w1:t3 or w1:p4
fn notify(title: string, body?: string)
Raise a herdr toast on the attached client. Records whether it was actually shown — herdr answers with a reason when notifications are disabled in config.
ArgumentTypeDescription
titlestringNotification title
body?stringNotification body
fn server-stop()
Stop the herdr server. Reads its state first, so an already-stopped server is a no-op. Refuses to stop a LOCAL server that hosts the pane running this method — that would kill the swamp run and every agent with it — unless force is set.
fn server-reload-config()
Reload config.toml in the running server, after validating it with herdr's own config check. An invalid config is refused rather than reloaded into a live fleet, unless force is set.
fn server-live-handoff()
Hand the live panes of a running server to a freshly started one — the mechanism behind an in-place herdr upgrade. Fails when no server is running rather than silently doing nothing.
fn agent-manifests()
Report the agent-detection manifests the server is using: per-agent active version, whether it came from the bundle or a remote fetch, and any manifest herdr rejected. Read-only.
fn update-agent-manifests()
Fetch newer agent-detection manifests and reload them. Reads the current versions first so the result names exactly which agents moved — herdr's own output reports only the post-update state.
fn reload-agent-manifests()
Reload agent-detection manifests from disk without fetching, then read the resulting state back — the reload itself prints nothing, so success is verified rather than assumed.
fn session-stop(name: string)
Stop a named herdr session. Reads the session inventory first: an unknown or already-stopped session is a no-op. Refuses to stop the session hosting this method unless force is set.
ArgumentTypeDescription
namestringNamed session, or 'default'
fn session-delete(name: string)
Delete a named herdr session. A session that is still running is refused rather than discarded with its panes and agents, unless force is set; an unknown session is a no-op.
ArgumentTypeDescription
namestringNamed session to delete

Resources

status(infinite)— herdr client/server health: versions, protocol compatibility, socket path and named sessions
fleet(infinite)— Whole-session roll-up: workspaces, tabs, pane count and every agent with its state
agent(infinite)— One agent in one pane: kind, state, cwd, terminal title and the agent's own session id
output(infinite)— Terminal text captured from a pane or agent
action(infinite)— Outcome of a control method, one row per target, with what changed and what was skipped
container(infinite)— A workspace, tab, pane or worktree that a method created or reused
manifests(infinite)— Agent-detection manifests in force on the server: per-agent version, source and staleness
04Previous Versions13
2026.10.15.9MIT

2026.10.15.9

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8MIT

2026.10.15.8

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6MIT

2026.10.15.6

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5MIT

2026.10.15.5

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4MIT

2026.10.15.4

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3MIT

2026.10.15.3

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2MIT

2026.10.15.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1MIT

2026.10.15.1

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.14.2MIT(was none)

2026.10.14.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.

Modified 1 behaviors

2026.09.19.2

2026.09.19.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.17.1

2026.09.17.1

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.08.19.1
2026.08.08.1

2026.08.08.1

Server lifecycle, and an ssh transport so all of it works against a herdr on another host.

Added

  • SSH transport. Setting sshHost points the whole model at a remote herdr server; every existing method works unchanged against it. New global arguments: sshHost, sshUser, sshPort, sshIdentityFile, sshExtraArgs, remoteBinary. ssh is invoked with BatchMode=yes and ConnectTimeout=10 so an unattended run never blocks on a prompt; caller options are placed first, which is what makes them win.
  • Eight server/session methods: server-stop, server-reload-config, server-live-handoff, agent-manifests, update-agent-manifests, reload-agent-manifests, session-stop, session-delete.
  • New manifests resource — per-agent detection-manifest version, source (bundled vs remote), and any manifest herdr rejected with a warning.
  • status now also reports target / remote (which server it talked to) and configOk / configDetail from herdr's own config check.

Changed

  • update-agent-manifests reads the current versions before updating, so its changedAgents names exactly which agents moved. herdr's own output reports only the post-update state, which cannot answer "did anything change?".
  • server-reload-config refuses to reload a config.toml that fails validation, rather than pushing a broken config into a live fleet.

Security

  • Over ssh a remote shell is unavoidable, so every argument is POSIX single-quoted with no "looks safe, skip it" fast path. The quoting is proved by round-tripping through a real /bin/sh in the property suite — a hand-written decoder could share a blind spot with the encoder.
  • The self guard does not fire against a remote fleet. HERDR_PANE_ID names a pane on the LOCAL server, and herdr numbers panes per session, so a local w1:p4 and a remote w1:p4 are unrelated panes that share a string. Matching there would refuse legitimate remote closes and silently skip legitimate remote prompts.
  • server-stop refuses to stop a LOCAL server that hosts the pane running the method; session-stop / session-delete refuse the session in use. session-delete also refuses a still-running session unless forced.
05Stats
A
100 / 100
Downloads
74
Archive size
45.3 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels