main
Herdr extension
Interact with the Herdr terminal workspace manager from inside a Pi session: inspect sibling agents, spawn workspaces/tabs/panes/worktrees, launch commands or agents in them, and prompt or wait on other agents.
The extension registers nothing when Pi is not running inside Herdr
(HERDR_ENV != 1), so it is inert outside a Herdr pane.
Not to be confused with ../herdr-agent-state.ts, which is installed and
overwritten by Herdr itself (it reports this pane’s agent state back to Herdr).
That file is managed by herdr integration; do not edit it.
Requirements
herdronPATH, with a running Herdr server.
Tool: herdr
| Action | Params | Notes |
|---|---|---|
agent-list |
— | All agents with status, pane id and cwd |
workspace-list |
— | Workspaces with status and counts |
pane-current |
— | Which pane/tab/workspace this session runs in |
agent-read |
target, lines, source |
Terminal output of a pane |
agent-wait |
target, until[], timeout |
Block until an agent settles |
agent-prompt |
target, text, until[], timeout |
Send a prompt; until/timeout imply --wait |
workspace-create |
cwd, label, env[], focus |
Returns the new pane id |
tab-create |
workspace, cwd, label, env[], focus |
Returns the new pane id |
pane-split |
target (default: current), direction, cwd, env[], focus |
Returns the new pane id |
worktree-create |
branch, base, cwd, label, focus |
Git worktree in its own workspace |
pane-run |
target, command[] |
Run a command in an existing pane |
agent-start |
target, kind, name, timeout |
Launch pi/claude/codex/… in a pane at a shell prompt |
notify |
text (title), body |
Herdr notification |
Typical spawn flow: workspace-create (or pane-split / worktree-create)
→ take paneId from the result → pane-run or agent-start in it.
All state-changing actions (everything except the reads and notify) go through
an approval dialog. Approvals are serialized through a mutex, because parallel
ui.select() dialogs deadlock the TUI — call write actions one at a time.
Command
/herdr— overview of workspaces and running agents, plus this pane’s id.
Implementation notes
Herdr’s CLI answers with a JSON envelope on stdout
({"id": ..., "result": {...}}), with three exceptions handled in
parseResponse():
- errors arrive on stderr as an envelope with a non-zero exit code;
pane readreturns raw terminal text;- action commands such as
pane runsucceed silently (exit 0, no stdout).
Creation responses use different shapes (workspace/root_pane vs pane);
extractPaneId() / extractWorkspaceId() normalize them.
Tests
make test # bun test herdr.test.ts
Fixtures are captured from the real CLI.