Using Herdr Effectively

Agent-Native Automation

Pick the smallest control surface that solves the job

Three layers

Layer	Use it for	Entry point
Agent skill	Agent operating Herdr from inside a pane	`herdr --skill`
CLI wrappers	Shell scripts, orchestration, debugging	`herdr agent ...`
Raw socket API	Custom clients and event subscriptions	`herdr api schema --json`

Controller-shell pattern

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." \
  --wait \
  --timeout 120000

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

Ordinary terminal pattern

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

Install the in-pane skill

npx skills add herdrdev/herdr \
  --skill herdr -g

# Or print the release-matched copy
herdr --skill

Choose by target

Use pane run for a shell, server, or test process. Use agent prompt --wait for a recognized coding agent. Do not use text scraping to infer agent lifecycle when the agent API is available.