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.
| Argument | Type | Required | Description |
|---|
| target | string | yes | Pane 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.
| Argument | Type | Required | Description |
|---|
| text | string | yes | Prompt 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.
| Argument | Type | Required | Description |
|---|
| targets | array | yes | Pane ids or agent names |
| failFast? | boolean | no | Abort 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.
| Argument | Type | Required | Description |
|---|
| pane | string | yes | Pane 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.
| Argument | Type | Required | Description |
|---|
| targets | array | yes | Pane ids or agent names |
| failFast? | boolean | no | Abort 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.
| Argument | Type | Required | Description |
|---|
| targets | array | yes | Pane ids |
| failFast? | boolean | no | Abort 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.
| Argument | Type | Required | Description |
|---|
| targets | array | yes | Pane ids |
| failFast? | boolean | no | Abort 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'.
| Argument | Type | Required | Description |
|---|
| pane | string | yes | Pane id to watch |
| match? | string | no | Literal substring to wait for |
| regex? | string | no | Regex 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.
| Argument | Type | Required | Description |
|---|
| label | string | yes | Workspace label — also the reuse key |
| cwd? | string | no | Working directory for the first pane |
| focus? | boolean | no | Focus 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.
| Argument | Type | Required | Description |
|---|
| label | string | yes | Tab label — also the reuse key |
| cwd? | string | no | Working directory for the tab's pane |
| env? | array | no | KEY=VALUE pairs for the pane |
| focus? | boolean | no | Focus 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.
| Argument | Type | Required | Description |
|---|
| pane | string | yes | Pane to split |
| cwd? | string | no | Working directory for the new pane |
| env? | array | no | KEY=VALUE pairs for the pane |
| focus? | boolean | no | Focus 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.
| Argument | Type | Required | Description |
|---|
| branch? | string | no | Branch to check out — the reuse key |
| base? | string | no | Base ref for a new branch |
| label? | string | no | Label for the worktree's workspace |
| focus? | boolean | no | Focus 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.
| Argument | Type | Required | Description |
|---|
| id | string | yes | Container 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.
| Argument | Type | Required | Description |
|---|
| title | string | yes | Notification title |
| body? | string | no | Notification 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.
| Argument | Type | Required | Description |
|---|
| name | string | yes | Named 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.
| Argument | Type | Required | Description |
|---|
| name | string | yes | Named 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