Herdr Docs

Workflow: Scripted Orchestration ​

Fresh

Herdr's CLI talks to the running server over the same local socket API used by integrations. Most commands print JSON, so scripts get deterministic automation. Agents themselves can drive Herdr from inside their panes.

flowchart TD
    A[Script or agent] --> B{Layer}
    B -->|simple| C[CLI wrappers: herdr pane/agent/wait]
    B -->|custom tools| D[Raw socket: newline-delimited JSON]
    B -->|agent in a pane| E[Agent skill file + HERDR_ENV=1]
    C --> F[Herdr server]
    D --> F
    E --> F
    F --> G[Panes, agents, events]

Pattern: build-test-review pipeline ​

bash
# 1. structure
herdr workspace create --cwd ~/project --label api --no-focus
herdr pane split 1-1 --direction right

# 2. run tests in one pane
herdr pane run 1-2 "npm test"
herdr wait output 1-2 --match "passing" --timeout 300000

# 3. spawn a reviewer agent and wait for it
herdr agent start reviewer --cwd ~/project --split down -- claude
herdr agent send reviewer "review the latest diff"
herdr agent wait reviewer --status idle --timeout 900000

# 4. collect the result
herdr agent read reviewer --source recent-unwrapped --lines 200

Pattern: agents controlling Herdr ​

Install the Herdr agent skill (see Agent Skill File) into any coding agent. When the agent runs inside a Herdr pane, HERDR_ENV=1 is set and the agent can:

  • inspect workspaces, tabs, panes, and neighboring agents
  • split panes and run commands without stealing focus
  • read pane output and recent logs
  • wait for servers, tests, or another agent to finish
  • start helper agents in sibling panes

The skill's guardrail: if HERDR_ENV=1 is not set, the agent stops and says it is not running inside a Herdr-managed pane.

Pattern: event-driven tooling ​

For long-lived watchers, subscribe to events over the raw socket (newline-delimited JSON over a Unix domain socket):

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

The first response acknowledges the subscription; later lines are pushed events. Use events.wait when you want one matching event and then a response.

Socket paths:

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

Resolution order: CLI --session <name>, then HERDR_SOCKET_PATH, then HERDR_SESSION=<name>, then the default socket.

Pattern: notifications from scripts ​

herdr notification show "build failed" --body "api workspace" --position top-left --sound request

Uses the configured [ui.toast] delivery. --sound can be none, done, or request.

See the Socket API for raw methods, response shapes, and protocol stability notes.