Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.
Abstract
The agenda bullet asks “Why Pi, Herdr, and Ghostty?” and the honest answer is architectural: none of the three is chosen for its features alone. Each is chosen because it leaves a seam open for the layer above it. Ghostty draws pixels and forwards keys. Herdr owns workspaces, tabs, and panes behind a unix-socket API that anything can call. Pi is a coding agent that runs inside those panes — and can call that same API. A Karabiner layer on top makes every capability a single chord. These notes trace each agenda bullet to the exact config line, CLI command, or captured server state that implements it, ending with a real swarm — one orchestrator, three workers — recorded the day before the workshop. The evidence shows mechanisms on one machine on one day; it does not measure how well the pattern transfers, and one worker outcome remains unverified.
Notice the stack, not the app
When you evaluate a terminal for agent work, the tempting mistake is to compare feature lists: which app has splits, which has AI built in. The setup examined here rejects that framing. It is a stack of four small layers, and the selection rule is visible in the configs: each layer exposes its state to the layer above.
Ghostty is only the renderer. Herdr — “terminal workspace manager for AI coding agents,” version 0.7.3 — runs as a client/server pair over a unix socket, and its help text exposes the whole workspace model as subcommands: workspace, tab, pane, agent, wait, notification (S3). 1
1. Checked live on the recorded workflow: herdr status reported client and server both at 0.7.3, protocol 16, socket at ~/.config/herdr/herdr.sock, server running (S3). Herdr is fast-moving pre-1.0 software; re-run the help commands before trusting any flag quoted here. ↩
Pi (version 0.80.10) is the agent that runs inside the panes. Herdr’s Pi integration installs an extension, herdr-agent-state.ts, that reports the agent’s state — idle, working, blocked — back to the server over the socket (S4). That is why a workspace listing can truthfully say which agents are busy: the agents report it themselves.
So the answer to “why these three” is an inference you can check against every section that follows: the stack is chosen so that keyboard software, shell scripts, and the agents themselves can all read and drive the same pane model. Where a monolithic terminal would need a plugin API, this setup needs only a socket and a CLI.
The test for your own setup: ask what your terminal will tell a script about its panes. If the answer is “nothing,” every pattern below is out of reach regardless of features.
Adjust the keyboard until every action is one chord
The first agenda bullet is “Karabiner setup with shortcuts.” The likely mistake when reading a 1,637-line karabiner.edn is to treat it as a pile of bindings. The load-bearing idea is a division of labor between two programs that cannot see what the other sees.
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 config binds each chord to a helper that receives the focused pane’s context. The Herdr config states this design in a comment: “Karabiner emits these internal chords only while Ghostty is frontmost; Herdr supplies the exact focused inner pane” (S1, S2). 2
2. The scoping mechanism is Karabiner’s application condition: the rules sit under an app id entry for Ghostty (com.mitchellh.ghostty) in karabiner.edn, so the chords do not exist in any other app (S1). ↩
Holding Esc turns the home row into a Herdr command deck. Figure 1 joins the two config files: the chord a hand actually presses, the internal chord Karabiner emits, and the command Herdr runs.
| Chord | Internal chord | Herdr action |
|---|---|---|
| Esc+Z | ctrl+alt+z | Open focused pane cwd in Zed |
| Esc+F | ctrl+alt+f | Open focused pane cwd in Finder |
| Esc+O | ctrl+alt+o | Smart open: URL, file:line reference, or cwd |
| Esc+E | ctrl+alt+e | Open latest file:line reference in Zed |
| Esc+R | ctrl+alt+r | Open current GitHub repository |
| Esc+P | ctrl+alt+p | Open PR for current branch |
| Esc+Y | ctrl+alt+y | Copy pane/repo context |
| Esc+L | ctrl+alt+l | Pick a URL from pane output (temporary picker pane) |
| Esc+Space | ctrl+alt+shift+l | Search all pane output; picking a hit focuses that pane |
| Esc+X | ctrl+alt+x | Open Codex in a pane to the right |
| Esc+N | ctrl+alt+n | Open Prompt Builder in a pane to the right |
| Esc+Return | — | herdr pane zoom --current --toggle |
Escape-mode chords in Ghostty and the Herdr commands they trigger
Figure 1. Derived display: escape-mode rules from karabiner.edn (S1) joined with the matching [[keys.command]] bindings and description strings in Herdr’s config.toml (S2). The join is editorial; each row’s chord and action text come from the named files.
Portability limit These chords exist only through this machine’s Karabiner config. On any other machine, none of the Esc chords fire. Herdr’s own portable bindings (splits on cmd+d, pane focus on cmd+alt+arrows, a tmux-style leader) still work everywhere (S2), so demos should distinguish the portable layer from the personal one.
One layer up, a comma simlayer jumps between projects: , plus a letter runs herdr-focus-or-open-workspace "<Label>" "<dir>", a helper that focuses a workspace matched by label, falls back to matching panes by working directory, creates the workspace if neither matches, then brings Ghostty forward (S1, S9).
The adjustment loop to copy is small: find an action you performed twice by hand, give it an internal chord in the keyboard layer, bind the chord to a context-aware command in the multiplexer, and watch whether your hands actually use it. Unused chords are config debt; delete them.
Test what the socket already knows
The second and third agenda bullets — search across panes, open the cwd anywhere — are both one question: what can a script learn about your panes without touching them? The way to find out is to run read-only queries and look at the answers. This sequence is safe on a live session:
# Who is running, and where? (all read-only)
herdr status
herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status] | @tsv'
herdr pane list --workspace wS | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'
herdr pane read wS:p1 --lines 10 # what that pane printed, without focusing it
herdr agent list # every detected agent and its reported state
Every convenience in Figure 1 is one of these queries plus an opener. “Open cwd in Zed” reads the focused pane’s working directory and hands it to Zed. “Search across panes to focus a pane” runs the same pane read over every pane, pipes the lines through a picker in a temporary pane, and focuses whichever pane produced the chosen line — the binding is declared type = "pane" in Herdr’s config precisely so the picker gets a real interactive surface (S2, S3).
The inference worth carrying home: once pane contents and pane cwd are queryable, “find the agent that mentioned the failing test and go there” stops being a feature you wait for and becomes a five-line shell script.
Run the queries on your own multiplexer of choice. If pane read has no equivalent, that is the observable failure signal for this whole approach — and the reason Herdr sits in the stack.
Explain the keeper: have Pi keep other panes alive
The agenda bullet “Have pi keep other panes alive” compresses two different mechanisms, and explaining the difference is the point of the segment.
The first sense is structural, and Herdr provides it without Pi’s help: the server keeps every pane alive whether or not a client window is attached. Quit Ghostty entirely; herdr reattaches to the same workspaces. The help text calls this the “persistent session” (S3).
The second sense is operational: keeping the agents inside those panes moving. Herdr injects HERDR_ENV, HERDR_PANE_ID, and HERDR_SOCKET_PATH into every pane (S5), so a Pi session in one pane can supervise its siblings with ordinary shell commands:
herdr agent list # states are reported by the agents, not guessed
herdr agent read learners --lines 40 # see what a sibling printed
herdr wait agent-status wS:pE --status idle --timeout 600000 # block instead of polling
herdr agent send learners "yes, apply the migration" # answer a stuck confirmation prompt
herdr pane run wS:pE "pi -p \"resume the brief in briefs/learners.md\"" # restart a dead worker
This is not hypothetical self-inspection. On the recorded workflow, a Pi session used pane capture to verify how glyphs rendered in its own Herdr pane — and in doing so surfaced a real bug in herdr pane run, recorded in that day’s conversation history (S7). 3
3. The conversation evidence is full-text-search excerpts from a local history index, not a replayable transcript. It supports “this happened and was discussed that day,” not any stronger claim about the bug’s scope or fix (S7). ↩
The workshop demo packages this as a “keeper” prompt: Pi loops over agent list, reads any sibling that is blocked or suspiciously idle, answers prompts, restarts crashes, interrupts loops, and blocks on wait agent-status between rounds. The prompt ends with two hard rules — never close panes, never start new work — because a shepherd with worker instincts destroys the flock’s legibility.
Intervention risk A 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. Stage a sacrificial workspace for the demo, and give a production keeper an allowlist of panes it may touch. The sources document the mechanism, not its safety record.
The feedback signal that the keeper is working: interventions get rarer over a session, because answered prompts and restarted workers stay answered and restarted. A keeper that intervenes constantly is masking a bad task split — fix the plan, not the babysitter.
Choose the plan before the swarm
The last bullet carries its own warning label: “Building swarms (lots of planning with a smart model first!).” The likely mistake is spawning workers because spawning is exciting. The choice that matters happens earlier: does this project decompose into tasks that are truly independent — separate directories, no shared files, no ordering? If not, redesign the split until it does, using the strongest model available. The fan-out itself is the cheap part.
The fan-out mechanism is chosen for observability. Herdr launches a worker as a direct process — herdr agent start <name> --cwd … -- <argv> — rather than typing a command into a shell. The orchestration extension’s README argues the consequence plainly: with argv launch “the launch race cannot happen, by construction,” and socket events make a dead child “an observable event within milliseconds, not a screen that stopped changing” (S5). 4
4. The extension (pi-herdr-subagents) is the presenter’s Herdr-native descendant of pi-interactive-subagents by HazAT, and its README credits that project as the origin of the orchestration model — spawn into visible panes, keep working, get woken by steer messages (S5). These are the author’s design claims about their own software, quoted as such. ↩
What does the shape look like when it is real? Figure 2 is a capture from the running server, taken the recorded workflow — the day before the workshop.
[
{ "pane_id": "wS:p1", "agent": "pi", "label": null, "foreground_cwd": "~/dev/pushing-boundaries" },
{ "pane_id": "wS:pE", "agent": "kimi", "label": "learners", "foreground_cwd": "~/…/sites/learners" },
{ "pane_id": "wS:pD", "agent": "kimi", "label": "execs", "foreground_cwd": "~/…/sites/execs" },
{ "pane_id": "wS:pC", "agent": "kimi", "label": "designers", "foreground_cwd": "~/…/sites/designers" }
]
Figure 2. Evidence display: pane list for the “pushing-boundaries” workspace, captured from herdr pane list on the recorded workflow, abridged to four fields with home paths shortened (S6). One Pi orchestrator pane and three worker panes, each labeled for its audience and confined to its own site directory.
Evidence limit The capture proves the swarm’s shape — planned decomposition into per-directory workers under one orchestrator — at one moment. It does not show whether the three sites were finished, how long they took, or how often the orchestrator intervened. The sources do not tell us the outcome.
The planning bias is also configured, not just preached: Pi’s settings on this machine pin the default thinking level to max (S4), and conversation history from earlier work shows the same rhythm under a different agent — iterative “research and decompose first, then implement via swarm” loops (S7).
The decision rule to take away: plan until independent, then fan out. If two workers would touch the same file, you are not done planning. If a worker can be described in one paragraph with a verifiable done-condition, it is ready for a pane.
Practical action
To rebuild the pattern on your own machine, in order:
- Audit the seam first. Ask your terminal setup for a pane list and a pane’s recent output from a script. No answer means change the multiplexer before touching keybindings.
- Wire three chords, not thirty: search-all-panes-to-focus, open-cwd-in-editor, open-repo. Success signal: a week later your hands use them without thinking. Unused chords get deleted.
- Rehearse the keeper safely. On a sacrificial workspace, start two trivial workers, wedge one on a confirmation prompt, and watch whether the keeper answers it and logs the intervention. Only then consider an allowlisted keeper near real work.
- Plan before spawning. Before any swarm, write the decomposition prompt with your strongest model at full thinking: independent tasks, one directory each, a done-condition each. If the model cannot make the tasks independent, do not spawn — re-plan.
- Launch by argv. Start workers as direct processes in visible panes, never by typing into shells, so death and completion are events you observe rather than screens you watch.