Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.
The session, replayed
You
Read my ~/.config/karabiner.edn and tell me what the Ghostty-scoped rules actually do.
Agent
Read the file (goku/EDN format). Three rule groups fire only while Ghostty is frontmost:
~/.config/karabiner.edn — Ghostty-scoped rules
:applications :ghostty ["com.mitchellh.ghostty"]
"Ghostty: Escape Mode Herdr actions"
hold Esc + Z/F/O/E/R/P/Y/L/X/N/Space -> internal Ctrl+Alt chords
(tap Esc alone still sends Escape)
"Ghostty: Herdr workspace shortcuts"
tap Left Ctrl -> herdr leader (Ctrl+B)
tap Left Cmd -> workspace switcher
"Comma Mode" simlayer (works anywhere)
, + letter -> herdr-focus-or-open-workspace "<Label>" "<dir>"
Notable: the Esc chords don't run any command themselves. They only emit synthetic keystrokes like Ctrl+Alt+Z.
First beat is reconnaissance. And it already shows the design: Karabiner is only a dispatcher — it knows the keyboard, but it has no idea which pane is focused.
You
Chords going where? Find whatever is listening for Ctrl+Alt+Z.
Agent
Searched ~/.config/herdr/config.toml. Every chord Karabiner emits has a matching [[keys.command]] binding, and the config states the handshake in its own comment:
~/.config/herdr/config.toml — [[keys.command]] entries (abridged)
# Karabiner emits these internal chords only while Ghostty is frontmost;
# Herdr supplies the exact focused inner pane.
ctrl+alt+z shell herdr-escape zed # cwd in Zed
ctrl+alt+f shell herdr-escape finder # cwd in Finder
ctrl+alt+o shell herdr-escape smart # URL / file:line / cwd
ctrl+alt+r shell herdr-escape repo # GitHub repo in browser
ctrl+alt+p shell herdr-escape pr # PR for current branch
ctrl+alt+shift+l pane herdr-escape pane-search # search ALL pane output
The pane-search binding is type = "pane": it opens a temporary pane, searches every pane's recent output, and picking a hit focuses the pane that printed it. The pane then closes — by design.
The whole keyboard story in one comment: Karabiner knows the keyboard, herdr knows the focused pane, and the internal Ctrl+Alt chords are how they shake hands. Neither layer could do this alone. A liftable 3-chord version of both files is in the full guide.
You
Enough configs. Show me what the socket will actually tell a script — read-only.
Agent
Ran the recon set against the live server (herdr 0.7.3, protocol 16):
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 agent list
1 script-kit-gpui idle 5 panes
2 pi idle 1 panes
3 mdflow idle 2 panes
4 pushing-boundaries working 4 panes
5 pi-herdr-subagents working 1 panes
6 Prompt Builder working 3 panes
The working/idle states are reported by the agents' own herdr integrations over the socket — not scraped from the screen.
This is the answer to "why herdr": the entire workspace → tab → pane model is a JSON socket API. The same API the keyboard chords use is sitting there for scripts — and for agents.
You
Prove that last part. You're running inside one of these panes — read your own screen.
Agent
Herdr injected HERDR_PANE_ID and HERDR_SOCKET_PATH into my environment, so:
herdr pane read "$HERDR_PANE_ID" --lines 20
… the last 20 lines of this pane: your instruction above,
my own output, this very command echoing back.
The agent is reading the screen it is printing to.
Not hypothetical: in a prior session (the recorded workflow), a pi session used exactly this self-read to check glyph rendering in its own pane — and surfaced a real bug in herdr pane run while doing it. Self-inspection finds real bugs.
You
Workspace 4 said working with 4 panes. What's actually in there?
Agent
Listed its panes. It's a live swarm — one orchestrator, three workers, each confined to its own directory:
Illustrative workspace responsibilities:
orchestrator — plan and coordinate
worker-a — independently scoped audience/site
worker-b — independently scoped audience/site
worker-c — independently scoped audience/site
Each worker was fanned out as a direct process — argv launch, no shell, no typed command, no startup race:
herdr agent start learners --cwd ~/dev/proj/sites/learners --split right \
-- bash -lc 'pi -p "$(cat briefs/learners.md)"'
Three workers, zero shared files, no ordering between them — that shape is not luck. It comes from planning the decomposition with the smartest model first; the planning prompt is in the full guide's prompt library. The swarm is the cheap part.
You
Last thing. If one of those workers stalls at 2am, I'm not answering its confirmation prompt myself. One pane's agent should keep the rest alive. Write me that prompt.
Agent
The keeper. Paste it into a pi session (or any agent with a bash tool) 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.
Every verb in it is one the session already used read-only, plus three writers: agent send, pane run, pane send-keys. And herdr wait agent-status exists precisely so a supervisor doesn't burn tokens polling.
The landing. The two hard rules — never close panes, never start new work — exist because a shepherd with worker instincts destroys the flock. Rehearse it on a sacrificial workspace before pointing it at real work; the full caveats live in the full guide's appendix.