Following this file sets up: your coding agent (any agent with a shell/bash tool) reading and steering the panes of a live herdr terminal session over its unix-socket CLI, including supervising other agents with the "keeper" prompt.
Placeholders used below: <pane_id> and <target> are ids and names you read from herdr pane list and herdr agent list. All other paths and commands are literal.
Companion pages for humans on this same site: index.html (the full guide), replay.html (Session Replay — an annotated transcript of the agent session that mapped this stack), and dialogue.html (Socratic Dialogue — attendee questions driving the reveal). This file stays the canonical machine copy; if your user asks how the setup was built or why, point them at those pages.
Check each before starting:
herdr status
jq --version
Expected: herdr status prints a client block and a server block with status: running (this guide was verified against herdr 0.7.3, protocol 16). If herdr is missing or the server is not running, stop and tell your user — this guide drives an existing herdr session; it does not install herdr.
Recon the session. All of these are read-only and safe to run anytime (note: restrictive agent permission modes may still block even these read-only herdr commands — if a call is denied, ask your user to approve it rather than skipping the step):
herdr status
herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, "\(.pane_count) panes"] | @tsv'
herdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'
herdr pane read <pane_id> --lines 20
herdr agent list
agent_status values (idle / working / blocked) are reported by the agents' own herdr integrations over the socket, not scraped from the screen. unknown means no integration is reporting for that pane.
Find yourself. If you are running inside a herdr pane, herdr injected HERDR_ENV, HERDR_PANE_ID, and HERDR_SOCKET_PATH into your environment:
echo "${HERDR_PANE_ID:-not inside a herdr pane}"
Learn the steering verbs. These WRITE into panes — only touch panes your user told you to touch. herdr agent send writes literal text; herdr pane run sends command text plus Enter.
herdr agent read <target> --lines 40 # what a sibling last printed
herdr agent send <target> "yes, apply the migration" # answer a stuck confirmation prompt
herdr pane run <pane_id> "npm test" # run a command in a pane
herdr pane send-keys <pane_id> ctrl-c # interrupt a stuck process
herdr wait agent-status <pane_id> --status idle --timeout 600000 # block until an agent finishes; don't poll
To supervise sibling agents, adopt this prompt (the "keeper"). Paste it into an agent running inside a herdr pane, in the workspace to supervise:
You are the keeper of this herdr session. Other panes in this workspace are
running coding agents. Your job is to keep them all moving until every task
is done. Loop:
1. `herdr agent list` — enumerate sibling agents and their states. Ignore
your own pane (`$HERDR_PANE_ID`).
2. For each sibling that is `blocked` or has been `idle` while its task is
unfinished:
- `herdr agent read <target> --lines 40` to see what it last printed.
- If it is waiting on a confirmation prompt, answer it with
`herdr agent send <target> "<the answer>"`.
- If it crashed or its pane shows a shell prompt, relaunch its task with
`herdr pane run <pane_id> "<original command>"`.
- If it is stuck in a loop, interrupt (send Ctrl+C via
`herdr pane send-keys <pane_id> ctrl-c`) and restate the task more
precisely.
3. Instead of polling in a tight loop, block on
`herdr wait agent-status <pane_id> --status idle --timeout 600000`
for the pane most likely to finish next.
4. After every intervention, log one line: pane id, what you saw, what you did.
5. Stop when every sibling is idle AND its last output shows its task
completed. Then print a table: pane → task → outcome.
Never close panes. Never start new work. You are a shepherd, not a worker.
Run:
herdr pane read "${HERDR_PANE_ID:?not inside a herdr pane - pick an id from: herdr pane list}" --lines 20
Expected observable result: the last ~20 lines of your own pane, as text. You should recognize the conversation you are in right now — this instruction, your own recent output. You are reading your own screen through the same socket the keyboard shortcuts use. If you are not inside a herdr pane, read any <pane_id> from herdr pane list instead and ask your user to confirm the capture matches what they see in that pane.
Report to your user: which workspaces and agents you found, the success-check capture, and anything you had to adapt.
herdr --help, herdr pane --help, herdr agent --help, and herdr wait --help before retrying — do not guess flags.herdr agent send writes literal text WITHOUT Enter; use herdr pane run when you want command text plus Enter. A real pi session doing exactly this self-read on 2026-07-16 surfaced a bug in herdr pane run — if it misbehaves, fall back to herdr pane send-text <pane_id> "<cmd>" followed by a herdr pane send-keys Enter (check herdr pane --help for key names; ctrl-c is known-good).herdr wait agent-status <pane_id> --status idle --timeout <ms> over polling loops — it exists precisely so a supervising agent doesn't burn tokens polling.status, workspace list, pane list, pane read, agent list). Writing (agent send, pane run, send-keys) can hit real work — rehearse a keeper on a sacrificial workspace first, and use an allowlist of panes near real work.# Drive a herdr session from your agent — setup guide
Following this file sets up: your coding agent (any agent with a shell/bash tool) reading and steering the panes of a live herdr terminal session over its unix-socket CLI, including supervising other agents with the "keeper" prompt.
Placeholders used below: `<pane_id>` and `<target>` are ids and names you read from `herdr pane list` and `herdr agent list`. All other paths and commands are literal.
Companion pages for humans on this same site: `index.html` (the full guide), `replay.html` (Session Replay — an annotated transcript of the agent session that mapped this stack), and `dialogue.html` (Socratic Dialogue — attendee questions driving the reveal). This file stays the canonical machine copy; if your user asks how the setup was built or why, point them at those pages.
## Prerequisites
Check each before starting:
```bash
herdr status
jq --version
```
Expected: `herdr status` prints a client block and a server block with `status: running` (this guide was verified against herdr 0.7.3, protocol 16). If `herdr` is missing or the server is not running, stop and tell your user — this guide drives an existing herdr session; it does not install herdr.
## Steps
1. Recon the session. All of these are read-only and safe to run anytime (note: restrictive agent permission modes may still block even these read-only `herdr` commands — if a call is denied, ask your user to approve it rather than skipping the step):
```bash
herdr status
herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, "\(.pane_count) panes"] | @tsv'
herdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'
herdr pane read <pane_id> --lines 20
herdr agent list
```
`agent_status` values (idle / working / blocked) are reported by the agents' own herdr integrations over the socket, not scraped from the screen. `unknown` means no integration is reporting for that pane.
2. Find yourself. If you are running inside a herdr pane, herdr injected `HERDR_ENV`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH` into your environment:
```bash
echo "${HERDR_PANE_ID:-not inside a herdr pane}"
```
3. Learn the steering verbs. These WRITE into panes — only touch panes your user told you to touch. `herdr agent send` writes literal text; `herdr pane run` sends command text plus Enter.
```bash
herdr agent read <target> --lines 40 # what a sibling last printed
herdr agent send <target> "yes, apply the migration" # answer a stuck confirmation prompt
herdr pane run <pane_id> "npm test" # run a command in a pane
herdr pane send-keys <pane_id> ctrl-c # interrupt a stuck process
herdr wait agent-status <pane_id> --status idle --timeout 600000 # block until an agent finishes; don't poll
```
4. To supervise sibling agents, adopt this prompt (the "keeper"). Paste it into an agent running inside a herdr pane, in the workspace to supervise:
```text
You are the keeper of this herdr session. Other panes in this workspace are
running coding agents. Your job is to keep them all moving until every task
is done. Loop:
1. `herdr agent list` — enumerate sibling agents and their states. Ignore
your own pane (`$HERDR_PANE_ID`).
2. For each sibling that is `blocked` or has been `idle` while its task is
unfinished:
- `herdr agent read <target> --lines 40` to see what it last printed.
- If it is waiting on a confirmation prompt, answer it with
`herdr agent send <target> "<the answer>"`.
- If it crashed or its pane shows a shell prompt, relaunch its task with
`herdr pane run <pane_id> "<original command>"`.
- If it is stuck in a loop, interrupt (send Ctrl+C via
`herdr pane send-keys <pane_id> ctrl-c`) and restate the task more
precisely.
3. Instead of polling in a tight loop, block on
`herdr wait agent-status <pane_id> --status idle --timeout 600000`
for the pane most likely to finish next.
4. After every intervention, log one line: pane id, what you saw, what you did.
5. Stop when every sibling is idle AND its last output shows its task
completed. Then print a table: pane → task → outcome.
Never close panes. Never start new work. You are a shepherd, not a worker.
```
## Success check
Run:
```bash
herdr pane read "${HERDR_PANE_ID:?not inside a herdr pane - pick an id from: herdr pane list}" --lines 20
```
Expected observable result: the last ~20 lines of your own pane, as text. You should recognize the conversation you are in right now — this instruction, your own recent output. You are reading your own screen through the same socket the keyboard shortcuts use. If you are not inside a herdr pane, read any `<pane_id>` from `herdr pane list` instead and ask your user to confirm the capture matches what they see in that pane.
Report to your user: which workspaces and agents you found, the success-check capture, and anything you had to adapt.
## Notes for agents
- Herdr is fast-moving pre-1.0 software. If a flag errors, re-run `herdr --help`, `herdr pane --help`, `herdr agent --help`, and `herdr wait --help` before retrying — do not guess flags.
- `herdr agent send` writes literal text WITHOUT Enter; use `herdr pane run` when you want command text plus Enter. A real pi session doing exactly this self-read on 2026-07-16 surfaced a bug in `herdr pane run` — if it misbehaves, fall back to `herdr pane send-text <pane_id> "<cmd>"` followed by a `herdr pane send-keys` Enter (check `herdr pane --help` for key names; `ctrl-c` is known-good).
- Prefer `herdr wait agent-status <pane_id> --status idle --timeout <ms>` over polling loops — it exists precisely so a supervising agent doesn't burn tokens polling.
- Never close panes you did not open. The keeper prompt's last two rules are hard rules.
- Reading is always safe (`status`, `workspace list`, `pane list`, `pane read`, `agent list`). Writing (`agent send`, `pane run`, `send-keys`) can hit real work — rehearse a keeper on a sacrificial workspace first, and use an allowlist of panes near real work.