Skip to content
These pages describe the newest preview build. For the current release, read the stable documentation.

Socket API

Herdsman exposes a local socket API for scripts and agents that need to inspect or control a running session.

Most automation should start with the CLI wrappers. Use the raw socket API only when you need direct request/response control or long-lived event subscriptions.

Layer Use it for
Agent skill Teaching a coding agent how to use Herdsman from inside a pane.
CLI wrappers Shell scripts, simple orchestration, and human debugging.
Raw socket API Custom tools, protocol clients, and event subscribers.

The layers share the same control surface.

The installed CLI can print the socket protocol schema bundled with that Herdsman binary:

Terminal window
herdsman api schema
herdsman api schema --json
herdsman api schema --output herdsman-api.schema.json

Plain herdsman api schema prints a short summary. --json prints the full JSON Schema document for tools, and --output PATH writes that document to a file. The schema covers raw requests, success responses, error responses, emitted events, and subscription events.

The socket API can:

  • create, list, focus, rename, and close workspaces
  • create, list, focus, rename, and close tabs
  • list, inspect, split, swap, focus, resize, rename, read, close, and send input to panes
  • list, inspect, read, prompt, wait on, rename, focus, start, and attach agents through CLI helpers
  • report custom agent state from hooks and plugins
  • subscribe to events and wait for output or state changes
  • install and uninstall built-in integrations
  • stop the server and reload config

Create a workspace:

Terminal window
herdsman workspace create --cwd ~/project --label api

Create a tab:

Terminal window
herdsman tab create --label logs

Split a pane and run a command:

Terminal window
herdsman pane split w1:p1 --direction right
herdsman pane run w1:p2 "npm test"

Inspect and rearrange panes:

Terminal window
herdsman pane layout --current
herdsman pane neighbor --direction right --current
herdsman pane resize --direction right --amount 0.1 --current
herdsman pane swap --direction right --current
herdsman pane zoom --on --current
herdsman pane split w1:p1 --direction right --ratio 0.333

Wait for an agent:

Terminal window
herdsman agent wait w1:p1 --until done

Read pane output:

Terminal window
herdsman pane read w1:p2 --source recent --lines 50

Raw socket method names use dot notation:

Area Methods
Server ping, server.stop, server.reload_config, server.agent_manifests, server.reload_agent_manifests
Notification notification.show
Client client.window_title.set, client.window_title.clear
Session session.snapshot
Workspace workspace.create, workspace.list, workspace.get, workspace.focus, workspace.rename, workspace.move, workspace.move_block, workspace.report_metadata, workspace.close
Worktree worktree.list, worktree.create, worktree.open, worktree.remove
Sections workspace.set_worktree_group
Tab tab.create, tab.list, tab.get, tab.focus, tab.rename, tab.move, tab.close
Pane pane.split, pane.swap, pane.move, pane.zoom, pane.layout, pane.process_info, pane.neighbor, pane.edges, pane.focus_direction, pane.resize, pane.list, pane.current, pane.get, pane.rename, pane.send_text, pane.send_keys, pane.send_input, pane.read, pane.report_agent, pane.report_agent_session, pane.report_metadata, pane.clear_agent_authority, pane.release_agent, pane.close, pane.wait_for_output
Stacks pane.stack, pane.stacks, pane.focus_stacked, pane.focus_stacked_at, pane.focus_stack_strip
Popup popup.close
Layout layout.export, layout.apply, layout.set_split_ratio
Equal pane sizes layout.equalize
Tab presets preset.list, preset.get, preset.save, preset.load, preset.apply, preset.default, preset.edit, preset.rename, preset.delete
Agent agent.list, agent.get, agent.read, agent.explain, agent.send_keys, agent.prompt, agent.wait, agent.rename, agent.focus, agent.start, agent.view.set, agent.view.clear
Events events.subscribe, events.wait
Integrations integration.install, integration.uninstall
Updates update.status, update.install, update.handoff, update.integrations, update.skip
Plugins plugin.link, plugin.list, plugin.unlink, plugin.enable, plugin.disable, plugin.action.list, plugin.action.invoke, plugin.log.list, plugin.pane.open, plugin.pane.focus, plugin.pane.close

agent.wait is server-owned and event-driven. It pins the resolved pane occupant so a replacement cannot satisfy the wait. agent.prompt accepts an optional wait object with until and timeout_ms; this submits the prompt and starts the wait in one request, avoiding a race between separate calls. If the resolved agent is already blocked, agent.prompt returns agent_blocked without sending input or starting the wait.

workspace.move_block atomically moves the ordered workspace_ids before before_workspace_id; omit the anchor to move the block to the end. The ids must be unique and the anchor cannot be part of the block. The response contains the authoritative ordered workspace list.

session.snapshot returns a one-time bootstrap snapshot for clients that keep their own local runtime cache. The response includes version/protocol metadata, focused workspace/tab/pane ids, workspace records, tab records, pane records, tab layout snapshots, and agent records. It is not a subscription. For cache bootstrap and recovery, subscribe first, then reconcile through authoritative reads as described under Event subscriptions below. Events invalidate cached state; they cannot be unconditionally replayed over a snapshot. Call session.snapshot again after reconnecting or when the local cache may be stale. Attached worktree provenance is included on workspace records. Full repo worktree discovery remains worktree.list.

From the CLI, herdsman api snapshot prints the live session.snapshot response as JSON for clients and agents that want a simple bootstrap command.

Pane control methods use public pane ids such as w1:p1. Methods whose schema makes pane_id optional use the server’s active focused pane when it is omitted. pane.move always requires the source pane_id.

pane.send_keys and pane.send_input.keys accept Herdsman key-combo strings: plain printable keys, special keys like enter and esc, modifier chords like ctrl+h, control+j, alt+x, and shift+tab, function keys like f1, and named punctuation like minus and plus. They do not accept prefix+ binding strings.

On macOS, pane.send_input (used by pane run) and agent.start check the terminal’s current canonical input limit before accepting a command into the input queue. An oversized encoded line, including Enter, is rejected in full; wait for the shell prompt and retry. Multiple short lines and raw-mode input remain supported. Successful responses still acknowledge queue admission, not command execution. This check covers the current submission only: it cannot inspect an earlier incomplete line or guarantee the terminal mode will remain unchanged while input is queued.

{"id":"req_current","method":"pane.current","params":{"caller_pane_id":"w1:p1"}}
{"id":"req_layout","method":"pane.layout","params":{"pane_id":"w1:p1"}}
{"id":"req_neighbor","method":"pane.neighbor","params":{"pane_id":"w1:p1","direction":"right"}}
{"id":"req_edges","method":"pane.edges","params":{"pane_id":"w1:p1"}}
{"id":"req_focus","method":"pane.focus_direction","params":{"direction":"right"}}
{"id":"req_resize","method":"pane.resize","params":{"pane_id":"w1:p1","direction":"right","amount":0.1}}
{"id":"req_zoom","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"toggle"}}
{"id":"req_input","method":"pane.input.set","params":{"pane_id":"w1:p1","right_click":"pane"}}
{"id":"req_split","method":"pane.split","params":{"direction":"right","ratio":0.333,"right_click":"pane","env":{"HERDSMAN_ROLE":"tests"}}}
{"id":"req_process","method":"pane.process_info","params":{"pane_id":"w1:p1"}}

pane.current returns a single PaneInfo. When caller_pane_id is present, Herdsman returns that pane. When it is omitted, Herdsman returns the active focused pane.

pane.input.set sets right_click to herdsman or pane for one pane. herdsman is the default. pane forwards unmodified right-click hold and drag gestures when the application requests terminal mouse reporting; otherwise Herdsman falls back to its pane menu. Right-clicking the pane frame always opens Herdsman’s menu. pane.split accepts the same optional right_click value for the newly created pane.

PaneInfo includes scroll when terminal scroll metrics are available:

{
"offset_from_bottom": 12,
"max_offset_from_bottom": 240,
"viewport_rows": 30
}

Clients can treat offset_from_bottom == 0 as at-bottom state.

Applications and plugins should emit the standard Kitty graphics protocol through their pane’s terminal output. Herdsman manages image placement, clipping, and visibility in compatible outer terminals.

The external socket pane-overlay API has been removed: pane.graphics.info, pane.graphics.set, pane.graphics.clear, and pane.graphics.stream are no longer available. There is no replacement socket image API. Internal wire compatibility with older servers does not restore these public methods.

pane.layout returns the tab layout snapshot with workspace_id, tab_id, zoomed, outer area, focused_pane_id, pane rects, and split rects/ratios. pane.neighbor and pane.edges include that same layout snapshot so clients can make the next decision without private layout state.

pane.process_info returns the pane’s shell pid, foreground process group id when available, and foreground processes with pid, name, argv/cmdline, and cwd when the platform exposes them.

layout.export returns a portable tab layout tree. Omit tab_id and pane_id to export the active tab, pass tab_id to export that tab, or pass pane_id to export the tab containing that pane.

{"id":"req_export","method":"layout.export","params":{"tab_id":"w1:t1"}}

The response includes workspace_id, tab_id, zoomed, focused_pane_id, and root. root is a BSP tree of pane and split nodes. Pane nodes can include pane_id, label, cwd, and argv command. Split nodes use direction (right or down), ratio, first, and second.

A stack node holds several panes in one slot: panes lists them in strip order, as pane fields without type, and active is the index of the visible one. layout.apply builds stacks from the same node.

layout.apply creates a fresh tab from a declarative tree. If tab_id is provided, Herdsman creates the replacement tab first and then closes the old tab. This restores structure, labels, cwd, env, and optional argv commands; it does not preserve live PTYs, scrollback, or running processes.

{
"id": "req_apply",
"method": "layout.apply",
"params": {
"workspace_id": "wabc",
"tab_label": "dev",
"focus": true,
"root": {
"type": "split",
"direction": "right",
"ratio": 0.65,
"first": {
"type": "pane",
"label": "editor",
"cwd": "/repo"
},
"second": {
"type": "pane",
"label": "tests",
"cwd": "/repo",
"command": ["sh", "-c", "just test"],
"env": { "HERDSMAN_ROLE": "tests" }
}
}
}
}

layout.set_split_ratio updates an existing split in a tab layout. The response is type: "layout_split_ratio_set" with the updated portable layout.

{"id":"req_ratio","method":"layout.set_split_ratio","params":{"tab_id":"w1:t1","path":[],"ratio":0.6}}

layout.equalize gives every column in a tab the same width ("dimension": "width") or every row the same height ("dimension": "height"), leaving the other dimension alone. A pane above or below split columns spans them, so the narrowest columns end up equal; a stack counts as one pane. Pick the tab with tab_id or pane_id, or omit both for the active tab. The response is type: "layout_equalized" with the updated portable layout.

{"id":"req_equal","method":"layout.equalize","params":{"tab_id":"w1:t1","dimension":"width"}}

Process-launching methods accept an env object. Herdsman applies those key/value pairs to the newly launched process only. Herdsman also injects HERDSMAN_SOCKET_PATH, HERDSMAN_ENV=1, HERDSMAN_WORKSPACE_ID, HERDSMAN_TAB_ID, and HERDSMAN_PANE_ID into managed pane processes. Herdsman-managed variables are authoritative when they conflict with caller-provided env.

pane.swap supports directional and explicit forms:

{"id":"req_swap_dir","method":"pane.swap","params":{"pane_id":"w1:p1","direction":"right"}}
{"id":"req_swap_explicit","method":"pane.swap","params":{"source_pane_id":"w1:p1","target_pane_id":"w1:p2"}}

Swap is same-tab only. It preserves split shape, split ratios, pane ids, and running processes. The response is type: "pane_swap" with changed, optional reason, source_pane_id, optional target_pane_id, focused_pane_id, and layout. Reason values are no_neighbor, same_pane, not_found, and cross_tab. When a tab is zoomed, swap keeps zoom active and mutates the hidden full-tab layout.

pane.move moves a running pane to a different tab, a new tab, or a new workspace:

{"id":"req_move_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"tab","tab_id":"w1:t2","target_pane_id":"w1:p3","split":"right","ratio":0.5},"focus":true}}
{"id":"req_move_new_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_tab","workspace_id":"w1","label":"logs"},"focus":true}}
{"id":"req_move_new_workspace","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_workspace","label":"logs","tab_label":"main"},"focus":true}}
{"id":"req_move_stack","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"stack","target_pane_id":"w1:p3"},"focus":false}}

A stack destination adds the pane to the stack in target_pane_id’s slot, from any tab or workspace; see Stacked panes.

Existing-tab moves require split: "right" | "down". target_pane_id is optional and defaults to the target tab’s focused pane. Same-tab layout changes remain pane.swap; moving to the source tab returns changed: false with reason: "same_tab". Moves involving a zoomed source or target tab return changed: false with reason: "zoomed_tab".

The response is type: "pane_move" with changed, optional reason, previous_pane_id, previous_workspace_id, previous_tab_id, the moved pane, optional source_layout, target_layout, optional created workspace or tab records, optional closed workspace or tab ids, and focused_pane_id. Cross-workspace moves keep the internal pane and terminal alive but assign a new public pane id in the destination workspace. Subscribers can listen for pane.moved; Herdsman does not emit fake pane close/create events for the moved terminal process.

pane.zoom toggles, enables, or disables zoom for the target pane’s tab:

{"id":"req_zoom_toggle","method":"pane.zoom","params":{"pane_id":"w1:p1"}}
{"id":"req_zoom_on","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"on"}}
{"id":"req_zoom_off","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"off"}}

Omitting pane_id targets the server’s active focused pane. The response is type: "pane_zoom" with changed, zoom_changed, focus_changed, optional reason, pane_id, focused_pane_id, zoomed, and layout. changed is true when either zoom state or focus changed. Reason values are single_pane, already_zoomed, and already_unzoomed.

The CLI wrapper for notification.show is:

Terminal window
herdsman notification show "build failed" --body "api workspace" --position top-left --sound request

Show a user notification through the configured toast delivery:

{"id":"req_notify","method":"notification.show","params":{"title":"build failed","body":"api workspace","position":"top-left","sound":"request"}}

title is required and must contain visible text after control characters and repeated whitespace are removed. body is optional. Herdsman collapses newlines, tabs, carriage returns, and repeated whitespace into spaces, then trims notification text to 80 characters for title and 240 characters for body. An empty sanitized title returns invalid_params. position is optional and applies only when ui.toast.delivery = "herdsman"; desktop positions are relative to the full Herdsman frame, and omitted positions use ui.toast.herdsman.position. Terminal, system, and off delivery ignore position. sound is optional and can be none, done, or request; it defaults to none and plays only when the notification is shown.

The response reports whether anything was shown:

{"id":"req_notify","result":{"type":"notification_show","shown":true,"reason":"shown"}}

Possible reasons are shown, disabled, rate_limited, no_foreground_client, and busy. disabled means ui.toast.delivery = "off". busy means an existing in-app toast was not replaced. Terminal and system delivery are best-effort through the current foreground attached Herdsman client.

Set or clear the foreground client’s outer terminal window title:

{"id":"req_title","method":"client.window_title.set","params":{"title":"herdsman api"}}
{"id":"req_title_clear","method":"client.window_title.clear","params":{}}

client.window_title.clear hands the title back to ui.window_title. The response is type: "client_window_title" with changed and reason set, cleared, or no_foreground_client.

Worktree methods manage Git checkouts as Herdsman workspaces. worktree.create creates a checkout and returns the new workspace, tab, root_pane, and worktree records. If the requested branch already exists locally, it checks out that branch; otherwise it creates the branch from the requested base or HEAD. worktree.open opens an existing checkout or returns the already-open workspace. worktree.remove runs git worktree remove against a linked child workspace and never deletes the branch.

Create a worktree from a source workspace:

{"id":"req_1","method":"worktree.create","params":{"workspace_id":"w1","branch":"worktree/api","focus":false}}

Open an existing checkout:

{"id":"req_2","method":"worktree.open","params":{"workspace_id":"w1","branch":"worktree/api","focus":true}}

Remove a linked checkout:

{"id":"req_3","method":"worktree.remove","params":{"workspace_id":"2","force":false}}

Use at most one of workspace_id or cwd for worktree.list, worktree.create, and worktree.open; omit both to use the active workspace. Use exactly one of path or branch for worktree.open. Raw socket cwd and path values must be absolute; the CLI expands relative --cwd and --path values before sending requests. Workspace responses include optional worktree provenance when a workspace belongs to a Herdsman worktree group. Worktree commands can emit workspace.updated when an existing workspace gains or changes worktree provenance.

Worktree commands also emit lifecycle events. worktree.create emits workspace.created, tab.created, pane.created, and worktree.created. worktree.open emits worktree.opened, and it also emits workspace/tab/pane creation events when it opens a new Herdsman workspace. worktree.remove emits worktree.removed; if the linked workspace is still open, it also emits workspace.closed.

workspace.close rejects closing a primary workspace while linked-worktree workspaces are open unless its params include "close_group": true, returning workspace_group_close_required when explicit group intent is missing. An explicit group close emits one workspace.closed event for each workspace it closes.

A stack is a layout slot holding several panes, one visible at a time.

{"id":"req_stack","method":"pane.stack","params":{"target_pane_id":"w1:p1","cwd":"/repo","focus":false}}
{"id":"req_stacks","method":"pane.stacks","params":{"workspace_id":"w1"}}
{"id":"req_member","method":"pane.focus_stacked","params":{"pane_id":"w1:p1","index":1}}
{"id":"req_next","method":"pane.focus_stacked","params":{"step":1}}
  • pane.stack opens a new pane in the slot of target_pane_id, else of the focused pane in workspace_id or the active workspace, and takes cwd, env, focus and right_click like pane.split. Without focus the new member starts hidden. The response is the new pane as type: "pane_info".
  • pane.stacks lists the stacks of workspace_id, or of every workspace, as type: "pane_stacks" with stacks[], each holding workspace_id, tab_id, pane_ids in strip order and visible_pane_id.
  • pane.focus_stacked shows and focuses a member of the stack holding pane_id, or the focused pane’s: pass exactly one of index, counting from 0, or step, the number of places from the visible member, wrapping. It answers with the focused pane; a pane outside a stack or an index past the last member changes nothing.
  • pane.focus_stack_strip resolves a click on a stack strip: column cells from the left edge of pane_id’s content, in a strip width cells wide, offset rows top or bottom (edge) of the content, 1 being the row next to it. It focuses the member drawn there, and pane_id itself for any other point. pane.focus_stacked_at is the older form without offset, meaning the row next to the content.

Focusing a hidden member by any method, pane.focus included, shows it. pane.list includes hidden members; pane.layout lists only visible panes.

A preset is a tab’s layout saved under a name, as a TOML file in the server’s config folder.

{"id":"req_save","method":"preset.save","params":{"name":"dev","pane_id":"w1:p2"}}
{"id":"req_load","method":"preset.load","params":{"name":"dev","workspace_id":"w2","focus":false}}
{"id":"req_pr","method":"preset.load","params":{"name":"pr","params":{"pr":"42"}}}
{"id":"req_apply","method":"preset.apply","params":{"name":"dev","tab_id":"w3:t1"}}
{"id":"req_default","method":"preset.default","params":{"kind":"worktree","workspace_id":"w1"}}
  • preset.save saves a tab as name: the tab tab_id, the tab holding pane_id, or the active tab. It refuses a name already taken (preset_exists) unless overwrite is true. The response, like preset.get’s and preset.rename’s, is type: "preset_info" with preset: name, label (the tab’s name), path (the file on the server’s machine), params and root.
  • root is a tree like layout.export’s: split nodes with direction, ratio, first and second, stack nodes with panes and active, and pane nodes. A pane holds label, cwd (relative to the workspace’s folder unless absolute), command (a command line typed into the pane’s shell) and env.
  • preset.load opens a preset as a new tab in workspace_id, the workspace holding pane_id, or the active workspace, and focuses it unless focus is false. It answers as layout.apply does, with type: "layout_apply", and then types each pane’s command into its shell. params gives values for the preset’s parameters by name; every pane gets each as an environment variable, the name in upper case. A name the preset does not declare fails with unknown_preset_param, a required one left out with missing_preset_param, and a value holding NUL with invalid_preset_param; no tab opens.
  • preset.apply opens a preset in an existing tab, tab_id, in place of the panes it holds, and answers as preset.load does. It takes params and focus as preset.load does; an unknown tab fails with tab_not_found, checked after the preset and its values. The preset’s panes open in a new tab that takes the old one’s place, so layout.tab_id in the answer is the tab to use from then on. Clients use it to start a new workspace from a preset: create the workspace, then apply the preset to the tab in the answer.
  • preset.default answers type: "preset_default" with name, the preset the config’s [presets] names for a new workspace, or no name when it names none. kind is workspace (the default) or worktree; the folder that picks the repository is cwd, else workspace_id’s folder, else the active workspace’s. The name is not checked against the saved presets.
  • params, in preset.get’s and preset.list’s answers, lists the parameters a preset declares: name, required when it must be given, default and description.
  • preset.list answers type: "preset_list" with presets[]: name, path, label, panes (the pane count), params and, for a file that does not parse, error.
  • preset.get reads one preset; preset.rename takes name and new_name; preset.delete answers type: "preset_deleted" with name; preset.edit opens the file in the server’s $VISUAL or $EDITOR in a popup pane and answers type: "ok".
  • Names use lowercase letters, digits, - and _. Errors: invalid_preset_name, preset_not_found, preset_exists, invalid_preset (with the file’s line), preset_io_failed and preset_edit_failed.

The methods behind Update without restarting. They act on the server you send them to.

{"id":"req_status","method":"update.status","params":{}}
{"id":"req_install","method":"update.install","params":{}}
{"id":"req_handoff","method":"update.handoff","params":{}}
{"id":"req_integrations","method":"update.integrations","params":{}}
{"id":"req_skip","method":"update.skip","params":{"version":"0.5.0"}}
  • update.status answers type: "update_status" with status: running (the server’s version), installed (the binary on disk, when it is another version), available (a newer release on channel, unless it is installed or skipped), self_update (whether this install updates itself; when not, install_command says how), installing and install_error, handoff ("ready" when the server can move to the binary on disk, "unsupported" when it must restart instead) and handoff_error, integrations[] (each outdated integration’s agent, installed and expected versions and paths), auto (present when automatic mode is on, with waiting_for: agents_busy or recent_input) and skipped.
  • update.install starts installing available in the background and answers with the status at once, with installing: true. Ask update.status until installing is false: then handoff is "ready", or install_error says what went wrong. Errors: self_update_unsupported, no_update.
  • update.handoff moves the server to the binary on disk, as server.live_handoff does, and answers before the server’s connections close. Errors: nothing_to_hand_off, handoff_unsupported, handoff_failed (the old server keeps running).
  • update.integrations updates every installed integration that is out of date and answers type: "integrations_updated" with updated[]: agent and paths. It never installs a new one.
  • update.skip remembers version as skipped, so available leaves it out, and answers with the status.

agent.view.set installs one transient declarative projection for the built-in Agents view. The projection is reevaluated whenever agent facts or current UI context change. It controls the expanded and collapsed sidebar, mobile Agents list, mouse targets, indexed focus, and next/previous Agent navigation. It does not change agent.list, notifications, detection, or global attention counts.

Show agents in the currently presented Space or agents needing attention elsewhere, then order by attention and most recent state transition:

{
"id": "view_set",
"method": "agent.view.set",
"params": {
"source": "plugin:example.agent-views",
"label": "focus",
"filter": {
"op": "any",
"filters": [
{
"op": "eq",
"field": "workspace_id",
"value": {"context": "current_workspace_id"}
},
{
"op": "in",
"field": "status",
"values": ["blocked", "done"]
}
]
},
"sort": [
{"field": "attention", "order": "desc"},
{"field": "state_change_seq", "order": "desc"}
]
}
}

Filter nodes use op values all, any, not, eq, in, or exists. Built-in filter fields are status, workspace_id, tab_id, pane_id, agent, seen, and state_change_seq. Use {"token":"name"} as a field to filter plugin-reported pane metadata. Values are strings, booleans, unsigned numbers, or a context object. Context values are current_workspace_id and current_tab_id, and may only be compared to the matching ID field. In a saved-machine client, the selected server’s view applies to the combined agent list. Current workspace and tab context includes that selected machine, so an identical ID on another machine does not match; independent filter branches, such as status being blocked, still match agents on any connected machine. Effective status values are idle, working, blocked, done, and unknown; done means idle and not yet seen.

Sort fields are workspace_order, tab_order, pane_order, attention, status, agent, seen, state_change_seq, or {"token":"name"}. Sorts are stable, evaluated in order, and accept asc or desc. Missing values stay after present values. When sort is omitted, the existing ui.agent_panel_sort policy remains active. A custom sort temporarily replaces that policy without rewriting config.

source identifies the owner. Plugins use plugin:<HERDSMAN_PLUGIN_ID>; Herdsman rejects plugin-owned sets when that plugin is missing or disabled. Other callers may use their own non-plugin: source. A successful set atomically replaces the previous view. The view lasts until it is cleared, replaced, its owning plugin is disabled, unlinked, or uninstalled, or the server exits. Plugins that want durable behavior should save the query under HERDSMAN_PLUGIN_STATE_DIR and reapply it from a [[startup]] hook.

Clear unconditionally, or only when the named source still owns the view:

{"id":"view_clear","method":"agent.view.clear","params":{}}
{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}

A source mismatch leaves the active view unchanged. Set and clear responses use type: "agent_view" and report active, source, and optional label.

The plugin API is an early interface for executable workflow tools. A plugin is a package with a herdsman-plugin.toml manifest. The manifest declares startup hooks, shareable actions, event hooks, terminal pane entrypoints, and link handlers. Startup hooks run once after restore when the API is ready. Actions and panes are manifest-only; runtime action registration and runtime argv pane creation are not part of v1.

Installed and linked plugins persist across restarts. Herdsman writes a plugins.json registry file alongside session.json on plugin.link, plugin.unlink, plugin.enable, and plugin.disable. The herdsman plugin install and herdsman plugin link CLIs also write the same registry when Herdsman is not running, then startup loads it automatically. On startup, Herdsman re-reads each manifest from its original path; if the file is missing or unparseable, the entry is kept with a warnings field so plugin.list surfaces it.

Herdsman validates event hook on values against known event names at link time. An unrecognised name does not block the link, but the returned plugin info includes a warning (e.g. "unknown event 'worktree.craeted'"). Check the warnings field in the plugin.link and plugin.list responses.

Link a local plugin manifest:

{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/path/to/plugin","enabled":true}}

plugin.link also accepts optional source metadata. The CLI uses this when it installs from GitHub so plugin.list can show origin, requested ref, resolved commit, and managed checkout path:

{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/managed/plugin/herdsman-plugin.toml","enabled":true,"source":{"kind":"github","owner":"remziduzagac","repo":"herdsman-plugin-examples","subdir":"worktree-bootstrap","requested_ref":"main","resolved_commit":"abc123","managed_path":"/data/plugins/github/<managed-checkout>","installed_unix_ms":1780000000000}}}

The path can be a plugin directory containing herdsman-plugin.toml or a direct manifest path. The manifest shape is:

id = "example.worktree-bootstrap"
name = "Worktree Bootstrap"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "Prepare new worktrees"
platforms = ["linux", "macos", "windows"]
[[build]]
command = ["bun", "install"]
[[actions]]
id = "bootstrap"
title = "Bootstrap worktree"
contexts = ["workspace"]
command = ["bun", "run", "bootstrap.ts"]
[[events]]
on = "worktree.created"
command = ["bun", "run", "bootstrap.ts"]
[[panes]]
id = "board"
title = "Worktree board"
placement = "overlay"
command = ["bun", "run", "board.ts"]
[[link_handlers]]
id = "github-issue"
title = "Open GitHub issue"
pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
action = "bootstrap"

min_herdsman_version is required. The server refuses to link a plugin when the field is missing, invalid, or newer than the running Herdsman binary.

herdsman also accepts min_herdr_version instead of min_herdsman_version, or beside it, as Plugins describes. Plugin info then reports it as min_herdr_version, and min_herdsman_version is empty when the manifest gives only min_herdr_version.

Declare platforms at the top level with the OS identifiers (linux, macos, windows) your plugin supports. Omitting platforms is allowed for local development. plugin.link succeeds, but the response includes a warning. Individual build commands, actions, event hooks, panes, and link handlers can declare their own platforms to override the plugin-level list; if omitted they inherit from the plugin. Invoking an action or opening a pane whose effective platforms do not include the current OS returns a platform_unsupported error.

List, enable, disable, or unlink linked plugins:

{"id":"req_plugin_list","method":"plugin.list","params":{}}
{"id":"req_plugin_disable","method":"plugin.disable","params":{"plugin_id":"example.worktree-bootstrap"}}
{"id":"req_plugin_enable","method":"plugin.enable","params":{"plugin_id":"example.worktree-bootstrap"}}
{"id":"req_plugin_unlink","method":"plugin.unlink","params":{"plugin_id":"example.worktree-bootstrap"}}

Actions are resolved from the linked manifest. plugin.action.list returns all actions across installed plugins; pass plugin_id to filter.

{"id":"req_plugin_actions","method":"plugin.action.list","params":{}}
{"id":"req_plugin_actions_filtered","method":"plugin.action.list","params":{"plugin_id":"example.worktree-bootstrap"}}

plugin.action.list returns each action’s effective platforms after applying plugin-level inheritance.

Invoke an action by its qualified id or bare action id:

{"id":"req_plugin_invoke","method":"plugin.action.invoke","params":{"action_id":"example.worktree-bootstrap.bootstrap","context":{"invocation_source":"keybinding"}}}

plugin.action.invoke resolves the manifest action, starts the manifest command, and returns the Herdsman-built invocation context plus the started command log record. Missing context fields are filled from the active workspace, tab, focused pane, worktree provenance, and request id. Invoking an action from a disabled plugin returns a plugin_disabled error.

Herdsman injects HERDSMAN_SOCKET_PATH, HERDSMAN_BIN_PATH, HERDSMAN_ENV=1, HERDSMAN_PLUGIN_ID, HERDSMAN_PLUGIN_ROOT, HERDSMAN_PLUGIN_CONFIG_DIR, HERDSMAN_PLUGIN_STATE_DIR, HERDSMAN_PLUGIN_CONTEXT_JSON, and available HERDSMAN_WORKSPACE_ID, HERDSMAN_TAB_ID, and HERDSMAN_PANE_ID values. Action commands also receive HERDSMAN_PLUGIN_ACTION_ID; event hooks receive HERDSMAN_PLUGIN_EVENT and HERDSMAN_PLUGIN_EVENT_JSON; pane commands receive HERDSMAN_PLUGIN_ENTRYPOINT_ID.

List recent action and event command logs:

{"id":"req_plugin_logs","method":"plugin.log.list","params":{"plugin_id":"example.worktree-bootstrap","limit":20}}

Event hooks run for enabled installed plugins when Herdsman emits a matching event name such as worktree.created.

There is no Herdsman-managed plugin storage API in v1. HERDSMAN_PLUGIN_CONFIG_DIR and HERDSMAN_PLUGIN_STATE_DIR are path discovery only; plugins own their files, schemas, migrations, and cleanup.

Open a managed terminal UI:

{"id":"req_plugin_pane","method":"plugin.pane.open","params":{"plugin_id":"example.board","entrypoint":"board","placement":"zoomed","target_pane_id":"w1:p1","env":{"HERDSMAN_ROLE":"board"},"focus":true}}

plugin.pane.open requires an installed, enabled, platform-compatible plugin, then launches the requested manifest [[panes]] entrypoint as an argv-backed terminal pane. Manifest pane placement defaults to overlay; request placement overrides the manifest with overlay, popup, split, tab, or zoomed. Overlay and popup placements use the active tiled pane as launch context. Popup terminals are session-modal and do not change the tab layout; optional width and height fields set their outer size as terminal cells or percentages such as "80%". Omitted dimensions default to half the terminal size, with too-small values clamped to the popup minimum. A popup has no pane ID, remains outside all pane.* and agent APIs, emits no pane lifecycle events, leaves plugin focus context on the underlying tiled pane, and does not export HERDSMAN_PANE_ID to its process. Popup launch returns ok; popup.close closes the active popup and returns popup_not_open when none exists. Split and zoomed panes target an existing pane; tab panes can target a workspace. Split, tab, zoomed, and overlay panes behave like normal Herdsman panes, and plugin.pane.focus and plugin.pane.close continue to operate on those panes.

Herdsman uses newline-delimited JSON over a local socket. On Unix, that socket is a Unix domain socket. On Windows, it is a named pipe.

Send one request per line:

{"id":"req_1","method":"ping","params":{}}

A successful response includes the same id:

{"id":"req_1","result":{"type":"pong"}}

For request lines that reach JSON decoding, error responses also echo the request’s id, including when the method or parameters are invalid. If the JSON is invalid or has no unambiguous top-level string id, the error response uses an empty id. Transport errors, such as invalid UTF-8, can close the connection without a response.

Event subscriptions keep the connection open after the initial response.

The default socket lives under your Herdsman config directory.

Named sessions have separate sockets:

~/.config/herdsman/herdsman.sock
~/.config/herdsman/sessions/<name>/herdsman.sock

Resolution order:

  1. explicit CLI --session <name>
  2. HERDSMAN_SOCKET_PATH
  3. HERDSMAN_SESSION=<name>
  4. default session socket

Use HERDSMAN_SOCKET_PATH only for low-level overrides.

For plugins, prefer invoking HERDSMAN_BIN_PATH and the CLI wrappers when you need portable Windows behavior. Raw socket clients are responsible for using the platform-native local socket form.

Integrations report agent state with pane.report_agent.

{
"id": "req_1",
"method": "pane.report_agent",
"params": {
"pane_id": "w1:p1",
"source": "custom:docs",
"agent": "docs-bot",
"state": "working",
"message": "building docs"
}
}

state carries semantic agent state and affects waits, notifications, and rollups. Report display-only values separately through metadata.

Session-only official integrations report native session references with pane.report_agent_session. State-reporting integrations can still include native session references in pane.report_agent. State-independent session reports do not affect waits, notifications, or rollups.

{
"id": "req_2",
"method": "pane.report_agent_session",
"params": {
"pane_id": "w1:p1",
"source": "herdsman:codex",
"agent": "codex",
"agent_session_id": "..."
}
}

Both methods accept an optional resume_argv array with the command that resumes the reporter’s current session after a Herdsman server restart. Its first element must be a plain command name, not a path. It allows at most 64 elements and 8 KiB in total, and no element may contain an apostrophe or control character; invalid values fail with invalid_resume_argv and the report is not applied. A custom agent must hold the pane through pane.report_agent before it can attach a command; otherwise the request fails with resume_not_accepted. Herdsman keeps the command only while the same source and agent hold the pane, and it takes precedence over Herdsman’s built-in resume command for that agent. Older Herdsman versions ignore the field.

{
"id": "req_3",
"method": "pane.report_agent_session",
"params": {
"pane_id": "w1:p1",
"source": "custom:my-agent",
"agent": "my-agent",
"agent_session_id": "...",
"resume_argv": ["my-agent", "--resume", "..."]
}
}

pane.get, pane.list, agent.get, and agent.list expose a read-only agent_session object when Herdsman has a stored native session reference:

{
"agent_session": {
"source": "herdsman:codex",
"agent": "codex",
"kind": "id",
"value": "..."
}
}

If no native session reference is stored, the field is omitted.

pane.get, pane.list, agent.get, and agent.list also expose foreground_cwd when Herdsman can resolve the cwd of the process currently controlling the pane PTY. The existing cwd field remains the pane/workspace cwd used for labels, follow-cwd behavior, and restored session state.

PaneInfo and AgentInfo expose optional terminal_title and terminal_title_stripped fields. terminal_title is the latest OSC 0/2 title after safety normalization. terminal_title_stripped removes one recognized leading activity or spinner glyph and following whitespace. These server-owned values are ephemeral across a cold restart and are independent of the metadata title and semantic agent state.

Use pane.report_metadata when a user hook wants to customize presentation without taking over lifecycle state from a Herdsman integration.

{
"id": "req_2",
"method": "pane.report_metadata",
"params": {
"pane_id": "w1:p1",
"source": "user:claude-title",
"agent": "claude",
"title": "Refactor auth middleware",
"display_agent": "Claude: auth",
"state_labels": {
"working": "refactoring auth",
"idle": "ready",
"done": "review ready"
},
"tokens": {
"summary": "refactor auth",
"model": "opus"
},
"ttl_ms": 3600000
}
}

Metadata reports are display-only. Valid metadata can override the pane title, displayed agent name, visible state labels, and arbitrary named tokens. working, blocked, idle, waits, notifications, and rollups still come from semantic state. Native session restore comes from stored official session references. agent is an optional guard for presentation fields against the authoritative agent label; applies_to_source similarly guards presentation fields against the active lifecycle authority source. These guards do not apply to token patches: token reporters own clearing and TTL refresh. Use display_agent to change the visible name. state_labels keys must be idle, working, blocked, done, or unknown.

Token maps are per-resource patches. A string sets a key, JSON null clears it, and omitted keys remain unchanged. The latest accepted update wins. Optional TTL applies independently to token keys updated by that report. Pane tokens are exposed by pane and agent get/list responses and can be rendered as $name in Agent sidebar rows. A report may mention at most 16 token keys, and a pane or workspace may retain at most 32 keys. Token names are 1–32 ASCII letters, digits, underscores, or hyphens.

Workspace tokens use the same contract:

{"id":"req_3","method":"workspace.report_metadata","params":{"workspace_id":"w1","source":"user:jj","tokens":{"jj_status":"2 changes","old":null},"ttl_ms":5000}}

Workspace get/list responses expose the resulting tokens map, and Space sidebar rows can render values such as $jj_status. Changes and TTL expiry emit workspace.metadata_updated with the latest workspace snapshot. This metadata event is available to API subscribers but does not invoke plugin event hooks.

Presentation text is normalized before storage. Herdsman trims surrounding whitespace, removes control characters, and caps title, display_agent, each state label, and token values at 80 characters. Empty normalized token values clear that key.

source and applies_to_source are source identifiers. They must be 80 characters or fewer and may contain only ASCII letters, digits, colon, dot, underscore, and hyphen.

Use ttl_ms for short-lived metadata. It must be between 1 and 86400000 milliseconds. Omit ttl_ms for metadata that should stay until replaced, cleared, or the pane/workspace closes. Presentation fields retain their existing source-scoped expiry behavior; each token updated by the call receives its own deadline. Token metadata is not restored after a server restart.

Use seq when a hook may send updates out of order. For the same source, reports with a sequence number less than or equal to the last accepted sequence are accepted by the API but ignored by the pane state. A pane or workspace accepts sequenced token reports from at most 32 distinct sources during its lifetime; clearing or expiry does not release those source slots.

Subscribe to events when you need a long-lived stream:

{
"id": "sub_1",
"method": "events.subscribe",
"params": {
"subscriptions": [
{ "type": "pane.agent_status_changed", "pane_id": "w1:p1", "agent_status": "blocked" }
]
}
}

The first response acknowledges the subscription. Later lines are pushed events. All entries must be valid: if any referenced pane does not exist, Herdsman rejects the entire request with an error and closes the connection. Refresh the pane list and retry rather than assuming the other entries were subscribed. Lifecycle subscriptions start when the request is accepted and do not replay events retained before that point.

Lifecycle and agent-status events are drained in bounded batches, in order within each subscription. Event history is not durable. If a subscriber falls behind the retained history, including while its subscriptions are being initialized, the server sends an error response with the original request id and error.code: "events_lost", then closes that subscription connection instead of silently continuing with missing events. Other clients remain connected. The history is shared across event types, so an overrun is reported even when the evicted events might not have matched this subscription’s filters.

On events_lost, treat the cached state as stale. Open a new subscription, wait for subscription_started, and keep reading while requesting session.snapshot on another connection. Use authoritative reads to reconcile current state: replace the cache with the snapshot, and treat incoming events as invalidation signals that trigger another read. Serialize refreshes and refresh again if events arrive while a read is in flight.

Snapshots and events have no shared sequence boundary. Ordering is guaranteed within each subscription entry, not across entries or relative to a snapshot, so do not unconditionally replay buffered event payloads onto the snapshot. Recovery restores current state, not the missing event history. Another events_lost requires resubscribing and reconciling again. Slow readers may need to increase read throughput or reduce event load.

workspace.set_worktree_group takes workspace_id and an optional group: a linked worktree’s workspace joins that section within its repository, and an absent or empty group takes it out. Sections were first called worktree groups, the name the API keeps. It answers with the workspace, whose tokens carry the group as worktree_group, and reports the change as workspace.metadata_updated. Other workspaces return not_a_linked_worktree; names longer than 64 characters or with control characters return invalid_worktree_group.

Workspace event subscriptions include workspace.created, workspace.updated, workspace.metadata_updated, workspace.renamed, workspace.moved, workspace.reordered, workspace.closed, and workspace.focused. workspace.metadata_updated reports token changes and TTL expiry without invoking plugin event hooks. Other workspace events describe Herdsman UI/runtime lifecycle. workspace.created includes optional workspace.worktree provenance when the workspace belongs to a worktree group. workspace.moved includes the moved workspace_id, requested insert_index, and updated ordered workspaces list. workspace.reordered includes the atomically moved workspace_ids, optional before_workspace_id, and authoritative ordered workspaces list. workspace.closed includes a final workspace snapshot when Herdsman can still identify it before removal. Tab event subscriptions include tab.created, tab.closed, tab.focused, tab.renamed, and tab.moved. tab.moved includes the moved tab_id, workspace_id, requested insert_index, and updated ordered tabs list for that workspace. Pane event subscriptions include pane.created, pane.updated, pane.closed, pane.focused, pane.moved, pane.exited, pane.agent_detected, pane.output_matched, pane.agent_status_changed, and pane.scroll_changed. pane.focused also reports manual pane selection changes from any client attached to this server. It does not move other clients’ views, and its payload does not identify the client. Selecting an already-selected pane does not emit it again. Terminal-title changes can emit pane.updated, but spinner-only raw-title changes do not emit it when terminal_title_stripped is unchanged. pane.scroll_changed is scoped to one pane_id and emits pane_id, workspace_id, and the current scroll metrics whenever Herdsman observes a changed scroll snapshot. Layout event subscriptions include layout.updated. The event carries the updated PaneLayoutSnapshot for one tab. Clients maintaining a cache with session.snapshot should use this event to refresh the affected layout through an authoritative read; a delayed payload may predate their latest snapshot.

Worktree event subscriptions include worktree.created, worktree.opened, and worktree.removed. Worktree events describe Git checkout lifecycle. worktree.created includes the opened workspace and created worktree. worktree.opened includes the target workspace, opened worktree, and already_open. worktree.removed includes the workspace_id, removed worktree, and forced.

Use events.subscribe for lifecycle events. Dedicated wait helpers are documented separately when a one-shot wait is supported.

Use pane.read through the CLI unless you are writing a protocol client.

Terminal window
herdsman pane read w1:p1 --source visible --lines 80
herdsman pane read w1:p1 --source recent --lines 120
herdsman pane read w1:p1 --source recent-unwrapped --lines 120
herdsman pane read w1:p1 --source detection

recent-unwrapped is useful for logs because it ignores soft wrapping. detection returns the bottom-buffer snapshot used by agent screen detection.

Use waits to coordinate agents and scripts.

Terminal window
herdsman agent wait w1:p1 --until done
herdsman agent wait w1:p1 --until blocked

Agent waits observe semantic state, not arbitrary command completion.

Successful responses look like this:

{
"id": "req_1",
"result": {
"type": "pane_info",
"pane": {
"pane_id": "w1:p1",
"terminal_id": "term_abc123",
"workspace_id": "w1",
"tab_id": "w1:t1",
"focused": true,
"agent_status": "working",
"revision": 42
}
}
}

server.agent_manifests returns the active agent detection manifest sources and remote update diagnostics without reloading rules:

{
"id": "req_1",
"result": {
"type": "agent_manifest_status",
"last_check_unix": 1781043522,
"last_result": "checked",
"manifests": [
{
"agent": "cursor",
"source": "/home/me/.config/herdsman/agent-detection/cursor.toml",
"source_kind": "local override",
"active_version": "2026.06.10.1",
"cached_remote_version": "2026.06.10.1",
"local_override_shadowing_remote": true,
"remote_update_result": "current"
}
]
}
}

Fields such as last_check_unix, last_result, active_version, cached_remote_version, remote_update_result, remote_update_error, remote_last_checked_unix, and warning are omitted when not available. server.reload_agent_manifests returns agent_manifest_reload with the same manifests item shape after reloading the in-memory rule cache.

agent.explain evaluates the target pane’s detection snapshot in the running server using the server’s active manifest cache:

{
"id": "req_2",
"method": "agent.explain",
"params": { "target": "w1:p1" }
}

The response contains the same explain object printed by herdsman agent explain --json, including the final state, manifest source and version, matched rule, evaluated rule evidence, skip-state reason, idle fallback reason, and screen_detection_skip_reason when a full lifecycle hook authority makes screen rules non-authoritative.

Clients need a running server that supports agent.explain; after upgrading Herdsman, restart or live-handoff the server before relying on this method.

Errors look like this:

{
"id": "req_1",
"error": {
"code": "not_found",
"message": "pane not found"
}
}

The client-rendered Herdsman UI uses a stable endpoint generation for local and SSH servers. Client and server builds do not need to match. During connection setup, they agree on the core snapshot, screen, input, and blob codecs, and the server advertises the API methods and optional capabilities it supports. Saved SSH federation requires the surface_interest capability so only the selected machine streams a pane surface and the health_check capability so a quiet broken connection cannot remain Online indefinitely. A server without this lifecycle support stays at Attention until it is explicitly updated. Other missing methods disable only those actions and show a client-local notice; they do not disconnect the UI. Rejected or timed-out actions are also reported without ending the connection. Servers from before endpoint generation 1 need one final update.

The numbered binary protocol remains for same-install and internal operations, including direct terminal attach and live handoff. Check ping or herdsman status before using those operations across different builds. JSON API clients should ignore unknown fields and handle unsupported methods as normal errors.