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:

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):

    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:

    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.

    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:

    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:

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

# 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.