Agentic Software Factory ยท July 17, 2026

Why Pi, Herdr, and Ghostty: One Keystroke from Agent to Swarm

An agentic terminal is a stack with open seams: Ghostty draws, Herdr serves every pane over a unix socket, Pi drives that socket from inside a pane, and Karabiner makes it all one keystroke.

TL;DR

๐Ÿค– Have your agent set this up โ€” paste this into it:

Fetch https://summit-inlet-kxyf.here.now/agent.md?raw and follow it to drive my herdr session from this agent. Run the success check at the end and show me the result.

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

pi (or any agent with a bash tool) inside a herdr pane any pane in the workspace you want supervised 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

your strongest model, thinking level maxed the project root you want to split up 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

any agent with a bash tool, inside a herdr pane the agent's own pane 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)

These steps mirror agent.md โ€” the machine copy your agent fetches. Placeholders: <pane_id> and <target> are ids and names from herdr pane list and herdr agent list.

  1. Check the prerequisites. herdr status must 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
  2. Recon the session read-only (the Quick start block above), then find yourself. Herdr injects HERDR_ENV, HERDR_PANE_ID, and HERDR_SOCKET_PATH into every pane:
    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. Note: agent send writes literal text; pane run sends 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
  4. 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.

The stack: each layer exposes its state to the one above

The tempting way to pick a terminal for agent work is comparing feature lists. This setup rejects that framing. It is four small layers, and the selection rule is visible in the configs: each layer exposes its state to the layer above.

Ghostty only draws pixels and forwards keys. Herdr (0.7.3, "terminal workspace manager for AI coding agents") runs as a client/server pair over a unix socket and surfaces the whole workspace โ†’ tab โ†’ pane model as CLI subcommands: workspace, tab, pane, agent, wait. The server keeps every pane alive with no window attached โ€” quit Ghostty entirely and herdr reattaches to everything. Pi (0.80.10) is the agent inside the panes; herdr's integration installs a pi extension that reports the agent's state โ€” idle, working, blocked โ€” back over the socket, so a workspace listing truthfully says which agents are busy because the agents report it themselves. Karabiner turns all of it into single keystrokes.

The test for your own setup: ask what your terminal will tell a script about its panes. If the answer is "nothing," everything below is out of reach regardless of features.

Two configs shake hands: keyboard to focused pane

Karabiner knows the keyboard but not which pane is focused. Herdr knows the focused pane but not global hotkeys. The handshake: Karabiner emits internal Ctrl+Alt+โ€ฆ chords only while Ghostty is frontmost, and herdr's [[keys.command]] bindings translate each chord into a command that receives the focused pane's context. The herdr config states the design in a comment: "Karabiner emits these internal chords only while Ghostty is frontmost; Herdr supplies the exact focused inner pane."

Holding Esc turns the home row into a herdr command deck:

Hold Esc +Action
Z / FOpen the focused pane's cwd in Zed / Finder
OSmart open: URL, file:line reference, or cwd โ€” whichever fits
EOpen the latest file:line reference in Zed
R / POpen the current GitHub repo / the PR for the current branch
YCopy pane/repo context
LPick a URL from pane output (temporary picker pane)
SpaceSearch ALL pane output; picking a hit focuses that pane
X / NOpen Codex / Prompt Builder in a new pane
ReturnZoom the focused pane

One layer up, a comma simlayer jumps between projects: , plus a letter focuses a workspace by label, falls back to matching panes by cwd, and creates the workspace if neither exists.

The three chords worth stealing (complete config)

Wire three chords, not thirty: open-cwd-in-editor, open-repo, and search-all-panes-to-focus. Three files. The helper script is a minimal, self-contained stand-in for the presenter's personal 1,200-line helper (see appendix) โ€” it needs herdr, jq, and per verb zed, gh, or fzf.

#!/bin/sh
# Focus-aware chord actions for a herdr session. chmod +x this file.
# Herdr injects HERDR_ACTIVE_PANE_ID when a [[keys.command]] binding fires.
set -eu
pane="${HERDR_ACTIVE_PANE_ID:-${HERDR_PANE_ID:?run from a herdr binding or pane}}"
cwd="$(herdr pane get "$pane" | jq -r '.result.pane.foreground_cwd')"
case "${1:-}" in
  zed)  zed "$cwd" ;;
  repo) cd "$cwd" && gh repo view --web ;;
  pane-search)
    herdr pane list | jq -r '.result.panes[].pane_id' | while read -r p; do
      herdr pane read "$p" --source recent-unwrapped --lines 200 2>/dev/null \
        | grep -v '^[[:space:]]*$' | sed "s|^|$p  |"
    done | fzf --no-sort --tac | awk '{print $1}' | xargs -r -n1 herdr agent focus ;;
  *) echo "usage: herdr-chords zed|repo|pane-search" >&2; exit 2 ;;
esac
# Karabiner emits these internal chords only while Ghostty is frontmost;
# Herdr supplies the exact focused inner pane.

[[keys.command]]              # Esc+Z -> open focused pane's cwd in Zed
key = "ctrl+alt+z"
type = "shell"
command = "$HOME/.local/bin/herdr-chords zed"

[[keys.command]]              # Esc+R -> open focused pane's GitHub repo
key = "ctrl+alt+r"
type = "shell"
command = "$HOME/.local/bin/herdr-chords repo"

[[keys.command]]              # Esc+Space -> search every pane, jump to the hit
key = "ctrl+alt+shift+l"
type = "pane"                 # runs in a temporary pane; it closes after you pick
command = "$HOME/.local/bin/herdr-chords pane-search"
;; Goku / Karabiner-Elements. Tap Esc = normal Esc.
;; Hold Esc + key = chord, only while Ghostty is frontmost.

;; under :applications
:ghostty ["com.mitchellh.ghostty"]

;; under :layers โ€” hold-Esc layer; tap still sends Esc
:escape-mode {:key :escape
              :params {:basic.to_if_alone_timeout_milliseconds 200
                       :basic.to_if_held_down_threshold_milliseconds 200}
              :alone [{:key :escape}]}

;; under :main โ€” the three chords
{:des   "Ghostty: Escape Mode Herdr actions"
 :rules [[:condi :ghostty :escape-mode]
         [:-z {:key :z :modi [:left_control :left_option]}]       ; Esc+Z
         [:-r {:key :r :modi [:left_control :left_option]}]       ; Esc+R
         [:spacebar {:key :l :modi [:left_control :left_option :left_shift]}]]} ; Esc+Space

The keeper: one agent babysits the rest

"Have pi keep other panes alive" is two mechanisms. Herdr keeps the panes alive structurally โ€” the server outlives every window. Pi keeps the agents in those panes alive operationally: because herdr injects the socket path and pane id into every pane, a pi session can supervise its siblings with ordinary shell commands โ€” read what a sibling printed, answer its stuck confirmation prompt, restart its crashed command, and block on herdr wait agent-status instead of burning tokens polling. That is the keeper prompt above, and its two hard rules โ€” never close panes, never start new work โ€” exist because a shepherd with worker instincts destroys the flock.

This is not hypothetical self-inspection. On July 16, 2026, a pi session used pane capture to check glyph rendering in its own herdr pane โ€” and in doing so surfaced a real bug in herdr pane run. The success check above is that same move, packaged.

The signal the keeper is working: interventions get rarer over a session. A keeper that intervenes constantly is masking a bad task split โ€” fix the plan, not the babysitter.

Swarms: plan until independent, then fan out

The agenda bullet carries its own warning label: "lots of planning with a smart model first!" The swarm is the cheap part; the plan is the whole game. Run the decomposition prompt above with your strongest model, and argue with the output โ€” if two workers would touch the same file, you are not done planning. Then fan out each brief into a visible pane as a direct process:

herdr agent start learners --cwd ~/dev/proj/sites/learners --split right \
  -- bash -lc 'pi -p "$(cat briefs/learners.md)"'

The argv launch matters: no shell, no typed command, no startup race โ€” "the launch race cannot happen, by construction" (the pi-herdr-subagents README, a herdr-native descendant of HazAT's pi-interactive-subagents). Death is observable too: herdr emits pane.exited socket events within milliseconds, so a dead worker is an event, not a screen that stopped changing. Captured from the running server the day before the workshop:

workspace "pushing-boundaries" โ€” herdr pane list, 2026-07-16 (abridged)
wS:p1  pi    (orchestrator)  ~/dev/pushing-boundaries
wS:pE  kimi  learners        ~/โ€ฆ/sites/learners
wS:pD  kimi  execs           ~/โ€ฆ/sites/execs
wS:pC  kimi  designers       ~/โ€ฆ/sites/designers

One pi orchestrator, three workers, each confined to its own directory โ€” exactly the shape the planning prompt demands. Every worker is watchable (glance at its pane), interruptible (click in and type), and composable with the keeper: one pane's pi can babysit the whole swarm.

Appendix

Limits & caveats
  • The Esc chords exist only through a Karabiner config. On a machine without it, none of them fire; herdr's portable bindings (splits on cmd+d, pane focus on cmd+alt+arrows, a tmux-style ctrl+b leader) work everywhere.
  • The live config's chords call herdr-escape, the presenter's personal 1,200-line Bun script with 12 verbs. The herdr-chords file above is a minimal 3-verb stand-in written for this page; its cwd lookup and search pipeline were tested piecewise on the live server, but it is not battle-tested.
  • The keeper writes into other panes: it answers prompts and reruns commands. Pointed at real work, a wrong guess becomes a wrong keystroke in a live session. Rehearse on a sacrificial workspace; give a production keeper an allowlist of panes it may touch.
  • Herdr is fast-moving pre-1.0 software (0.7.3, protocol 16, verified 2026-07-16). Re-run herdr --help and the subcommand helps before trusting any flag quoted here.
  • The swarm capture proves the swarm's shape at one moment. It does not show whether the three sites were finished, how long they took, or how often the orchestrator intervened.
  • The pane run bug anecdote comes from local conversation-search excerpts, not a replayable transcript. It supports "this happened that day," nothing stronger.
  • Pane-search opens a temporary pane (type = "pane") that disappears after selection โ€” by design, not a crash.
Provenance

All sources read on the presenter's machine on July 16, 2026, and re-verified against live --help output before this update: the Karabiner config (~/.config/karabiner.edn, Ghostty-scoped escape-mode rules and comma simlayer), herdr's config (~/.config/herdr/config.toml, [keys] and [[keys.command]] entries), live CLI output from herdr status / --help / pane / agent / wait subcommand help (herdr 0.7.3, protocol 16; pi 0.80.10), the installed herdr-agent-state.ts pi extension, the pi-herdr-subagents README (design claims quoted as the author's own, with its credit to pi-interactive-subagents by HazAT preserved), sanitized captures of herdr workspace list and herdr pane list from the running server, and local conversation-search excerpts. The keeper and decomposition prompts are printed verbatim from the workshop demo files. The three-chord Karabiner snippet is the live file's rules reduced to three chords, with personal layer resets removed; the herdr-chords helper was written for this page as a self-contained replacement for a personal script. Home directories are shortened to ~ throughout. No external requests; one local app.js for copy buttons โ€” the page reads fully without it.