SOP: Agent Orchestration from Scripts

Fresh

Start, monitor, and coordinate agents from shell scripts, CI tasks, or other agents using the Herdr CLI.

Prerequisites

• A running Herdr server (herdr status)
• For agent-driven control from inside a pane: the agent skill file installed and HERDR_ENV=1 present (see Agent Skill File)

Procedure: spawn and place an agent

1. Start an agent as a named target:

herdr agent start reviewer --cwd ~/project --split right -- pi

2. Or place it in a specific workspace and tab:

herdr agent start docs --workspace 1 --tab 1-1 -- claude

3. Create supporting structure without stealing focus:

herdr workspace create --cwd ~/project --label api --no-focus
herdr tab create --label logs

agent start vs pane run

Use herdr agent ... when the terminal should be treated as an agent target (shows in agent list, waitable by state, attachable by name). Use herdr pane ... for ordinary terminals, servers, and tests, e.g. pane split + pane run for cargo test.

Procedure: read and send

herdr agent read reviewer --source recent --lines 50
herdr agent send reviewer "explain the failing test"
herdr pane run 1-2 "npm test"

pane run submits text plus Enter atomically. Prefer it over send-text + send-keys Enter.

Read sources:

Source	Meaning
visible	Current rendered screen. Best for UI feedback loops
recent	Recent scrollback with terminal wrapping
recent-unwrapped	Recent scrollback without soft wrapping. Best for logs
detection	Bottom-buffer snapshot used by agent screen detection

Procedure: wait for completion

Wait on agent state:

herdr agent wait reviewer --status idle --timeout 600000
herdr wait agent-status 1-1 --status done
herdr wait agent-status 1-1 --status blocked

Wait on output for normal commands and servers:

herdr wait output 1-2 --match "Server running" --timeout 120000
herdr wait output 1-2 --match "tests? passed" --regex

Use wait output for commands/servers and wait agent-status for coding agents.

Procedure: report custom state from hooks

herdr pane report-agent 1-1 \
  --source custom:indexer \
  --agent docs-bot \
  --state working \
  --custom-status indexing

--state is semantic (drives waits, notifications, rollups). --custom-status is display-only.

For presentation-only changes next to a Herdr-managed integration, use metadata instead so you do not take over state authority:

herdr pane report-metadata "$HERDR_PANE_ID" \
  --source user:claude-title \
  --agent claude \
  --title "Refactor auth middleware" \
  --display-agent "Claude: auth" \
  --custom-status "refactor auth" \
  --ttl-ms 3600000

Procedure: attach for manual inspection

herdr agent attach reviewer            # one agent terminal, not the full UI
herdr agent attach reviewer --takeover # replace existing input owner
herdr terminal attach term_abc123      # same for a non-agent terminal

Detach with ctrl+b q. Send a literal ctrl+b with ctrl+b ctrl+b.

Example: end-to-end script

# Spawn a test runner pane and a reviewer agent, wait for both
herdr pane split 1-1 --direction right
herdr pane run 1-2 "npm test"
herdr agent start reviewer --cwd ~/project --split down -- claude
herdr agent send reviewer "review the diff in this repo"

herdr wait output 1-2 --match "passing" --timeout 300000
herdr agent wait reviewer --status idle --timeout 900000
herdr agent read reviewer --source recent-unwrapped --lines 120

Verification checklist

• [ ] herdr agent list shows the spawned agent with its name
• [ ] herdr agent wait returns when the state is reached
• [ ] Pane reads return the expected output