Lesson 05 · Using Herdr Effectively

Agent-Native Automation

Control agents deterministically without turning every task into keystroke scraping

Your tangible win

After this lesson, you can build a small controller workflow: create a place, start a recognized agent, send a bounded prompt, wait for its lifecycle state, and read the result.

The operating model

Use the smallest control surface that understands the target. Layout creates locations, panes control raw terminals, agents control recognized coding agents, and the socket API is the lower-level escape hatch.

One control surface, three entry points

flowchart TB C["Herdr control surface"] --> L["Agent skill"] C --> P["CLI wrappers"] C --> S["Raw socket API"] L --> I["Agent inside pane"] P --> H["Shell script or controller"] S --> X["Custom client or subscriber"] style C fill:#faf5ff,stroke:#9333ea,stroke-width:2px style L fill:#fef9c3,stroke:#ca8a04,stroke-width:2px style P fill:#dbeafe,stroke:#2563eb,stroke-width:2px style S fill:#f0fdf4,stroke:#16a34a,stroke-width:2px style I fill:#fef9c3,stroke:#ca8a04,stroke-width:2px style H fill:#dbeafe,stroke:#2563eb,stroke-width:2px style X fill:#f0fdf4,stroke:#16a34a,stroke-width:2px

Figure 1: The layers share Herdr's control surface; start with the CLI unless you need in-pane instructions or raw protocol access.

Layer	Best for	How you enter
Agent skill	A coding agent operating Herdr from inside a pane.	`herdr --skill` or install with `npx skills`.
CLI wrappers	Shell scripts, simple orchestration, and human debugging.	`herdr pane ...` and `herdr agent ...`.
Raw socket API	Custom protocol clients and long-lived event subscriptions.	`herdr api schema --json`.

Primitive selection

Herdr's three operational primitives are deliberately separate:

flowchart TB W["Layout"] --> P["Pane"] P --> A["Agent"] W --> W1["Create workspace, tab, split"] P --> P1["Run, send, read, wait output"] A --> A1["Prompt, wait state, read result"] style W fill:#dbeafe,stroke:#2563eb,stroke-width:2px style P fill:#f0fdf4,stroke:#16a34a,stroke-width:2px style A fill:#fef9c3,stroke:#ca8a04,stroke-width:2px style W1 fill:#dbeafe,stroke:#2563eb,stroke-width:2px style P1 fill:#f0fdf4,stroke:#16a34a,stroke-width:2px style A1 fill:#fef9c3,stroke:#ca8a04,stroke-width:2px

Figure 2: Build the location, choose raw-terminal or agent semantics, then wait using the matching primitive.

If the target is...	Use...	Why
A shell, server, or test runner	`pane run`	Submits a command and targets ordinary terminal output.
A recognized coding agent	`agent prompt`	Targets agent identity and interactive input.
An ordinary process's output	`pane wait-output`	Matches text or regex in terminal output.
An agent's lifecycle	`agent wait`	Understands `idle`, `done`, and `blocked`.

Build a controller workflow

Run this from a controller shell: outside Herdr or inside a dedicated Herdr shell pane. Do not run it inside the conversational input of another agent.

created=$(herdr workspace create \
  --cwd ~/project \
  --label review \
  --no-focus)
pane=$(printf '%s\n' "$created" |
  jq -r '.result.root_pane.pane_id')

herdr agent start reviewer \
  --kind codex \
  --pane "$pane"

herdr agent prompt reviewer \
  "Review src/api. Do not edit. Run focused tests.\
  Report findings by severity and include paths." \
  --wait \
  --timeout 120000

herdr agent read reviewer \
  --source recent-unwrapped \
  --lines 120

Workspace creation returns JSON. Capture the returned IDs; never predict w1:p1 or reuse a stale pane ID after moving a pane.

Automate ordinary terminals

Use pane commands for processes that are not recognized coding agents:

herdr pane run w1:p2 "npm test"
herdr pane wait-output w1:p2 \
  --match "Tests passed" \
  --timeout 120000
herdr pane read w1:p2 \
  --source recent-unwrapped \
  --lines 80

pane run submits a command with Enter atomically. Prefer it over manually combining send-text with send-keys enter.

Let an agent operate Herdr

Herdr ships a reusable skill file for a coding agent running inside a Herdr-managed pane. The skill is not a second service; it is markdown instructions that teach the agent to use the local CLI safely.

# Install globally for supported agents
npx skills add herdrdev/herdr \
  --skill herdr -g

# Or print the release-matched copy bundled with Herdr
herdr --skill

Inside a Herdr pane, the process has HERDR_ENV=1. With the skill installed, the agent can inspect sibling panes, split without stealing focus, read output, wait for tests, and start helper agents.

Boundary rule

An agent can control Herdr from inside its pane, but it should not casually mutate the user's layout. Use --no-focus, bounded scope, explicit verification, and a report contract for helper work.

When to use the socket API

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

herdr api schema
herdr api schema --json
herdr api schema --output herdr-api.schema.json

The schema describes raw requests, success and error responses, emitted events, and subscription events. It is the contract for custom protocol clients.

Checkpoint: match the primitive

Create the workspace or tab first.
Capture the returned root pane ID.
Start an agent only in an available shell pane.
Use agent prompt --wait for an agent turn.
Use pane run and pane wait-output for ordinary processes.
Read the result and verify it before acting on it.

A recognized Codex agent is working in a pane. Which command should wait for its lifecycle state?

Remember this

Layout creates the place. Pane commands control raw terminals. Agent commands control recognized agents. Use the socket API only when the wrappers are not enough.

Primary sources

This lesson follows Herdr's official Agent automation, Agent skill, CLI Reference, Socket API, and Integrations. Use the agent-native automation cheat sheet for retrieval practice.