Complete reusable prompts, setup recipes, success checks, and caveats for visible workspaces for agents and swarms.
Quick start
Read-only recon on a live herdr session. Nothing here focuses, closes, or writes to a pane — safe to run mid-talk. If an agent runs these for you under a restrictive permission mode, it may need you to approve even these read-only commands.
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 "$(herdr pane list | jq -r '.result.panes[0].pane_id')" --lines 10
herdr agent list
Prompt library
The keeper — keep every sibling agent alive
- Agent: pi (or any agent with a bash tool) inside a herdr pane
- Working directory: any pane in the workspace you want supervised
- Expected result: one log line per intervention, then a pane → task → outcome table
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.
Swarm decomposition — plan with your smartest model first
- Agent: your strongest model, thinking level maxed
- Working directory: the project root you want to split up
- Expected result: a table of worker briefs with a done-condition each — argue with it before spawning anything
Decompose this project into N independent tasks that can each be completed
by an agent working alone in its own directory, with no shared files and no
ordering between them. For each task: a directory, a one-paragraph brief, a
definition of done, and the exact command to verify it. If the tasks are
not truly independent, redesign the split until they are.
Self-check — make your agent read its own screen
- Agent: any agent with a bash tool, inside a herdr pane
- Working directory: the agent's own pane
- Expected result: the agent reports lines that match the conversation you are having with it
Run this with your bash tool:
herdr pane read "$HERDR_PANE_ID" --lines 20
That capture is your own pane — the screen you are printing to right now.
Tell me the last three lines and confirm they match this conversation.
Set it up (agent guide)
-
Check the prerequisites.
herdr statusmust show a running server (this page was verified against herdr 0.7.3, protocol 16). If herdr is not installed, stop — this guide drives an existing herdr session, it does not install one.herdr status jq --version -
Recon the session read-only (the Quick start block above), then find yourself. Herdr injects
HERDR_ENV,HERDR_PANE_ID, andHERDR_SOCKET_PATHinto every pane: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. Note:
agent sendwrites literal text;pane runsends command text plus Enter.herdr agent read <target> --lines 40 herdr agent send <target> "yes, apply the migration" herdr pane run <pane_id> "npm test" herdr pane send-keys <pane_id> ctrl-c herdr wait agent-status <pane_id> --status idle --timeout 600000 -
To supervise sibling agents, adopt the keeper prompt — printed complete in the Prompt library above and in agent.md.
Success check: read your own pane through the socket. The capture should show the conversation you are in right now — this instruction, your own recent output.
herdr pane read "${HERDR_PANE_ID:?not inside a herdr pane - pick an id from: herdr pane list}" --lines 20
… the last 20 lines of your own screen, as text.
You should recognize your current session in it — that is the point:
the same socket your keyboard uses is readable by the agent it hosts.
Complete reusable setup contract
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
-
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
herdrcommands — 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 listagent_statusvalues (idle / working / blocked) are reported by the agents' own herdr integrations over the socket, not scraped from the screen.unknownmeans no integration is reporting for that pane. -
Find yourself. If you are running inside a herdr pane, herdr injected
HERDR_ENV,HERDR_PANE_ID, andHERDR_SOCKET_PATHinto 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 sendwrites literal text;herdr pane runsends 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.
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
- Herdr is fast-moving pre-1.0 software. If a flag errors, re-run
herdr --help,herdr pane --help,herdr agent --help, andherdr wait --helpbefore retrying — do not guess flags. herdr agent sendwrites literal text WITHOUT Enter; useherdr pane runwhen you want command text plus Enter. A real pi session doing exactly this self-read in the observed snapshot surfaced a bug inherdr pane run— if it misbehaves, fall back toherdr pane send-text <pane_id> "<cmd>"followed by aherdr pane send-keysEnter (checkherdr pane --helpfor key names;ctrl-cis 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.