Visible workspaces for agents and swarms — questions and tradeoffs

Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.

Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.

The questions the room asks

Why not just tmux? It keeps panes alive too.

Persistence isn't the differentiator — the socket is. Herdr (0.7.3, "terminal workspace manager for AI coding agents") is a client/server pair whose entire workspace → tab → pane model is a JSON socket API surfaced as CLI subcommands. And agent status is reported by the agents themselves over that socket — a pi extension tells herdr idle/working/blocked — not scraped from the screen. The test for any terminal setup: ask what it will tell a script about its panes. If the answer is "nothing," everything else in this section is out of reach. Here's the read-only proof, safe to run mid-talk:

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

So the real trick is just Karabiner macros?

Half of it. Karabiner knows the keyboard but has no idea which pane is focused; herdr knows the focused pane but can't see global hotkeys. So 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. My config says it out loud in a comment. The herdr half:

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

Hold on — your live config has a dozen chords. That's a lot of muscle memory.

Mine grew over months; you should wire exactly three: open-cwd-in-editor, open-repo, and search-all-panes-to-focus. Tap Esc still sends Esc; holding it turns the home row into a command deck. The Karabiner half of the handshake:

;; 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

Thirty panes running — how do you find the one that printed the error?

Esc+Space. It searches the recent output of every pane, and picking a hit lands you focused in the pane that printed it. The search pane is temporary — it closes after you pick, by design. The primitive underneath is just herdr pane read across all panes piped through fzf; this helper is the complete third file of the kit:

#!/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

What happens when Ghostty crashes mid-swarm?

Nothing dies. Ghostty only draws pixels — the herdr server owns every workspace, tab, and pane, and it keeps them all alive with no window attached. Quit Ghostty entirely, relaunch, run herdr, and you reattach to everything exactly where it was. That split is also why the recon commands above are safe during a live talk: the reads go to the server, not to any window.

“An agent babysitting other agents” sounds like a demo gimmick.

It's ordinary shell commands. Herdr injects HERDR_PANE_ID and HERDR_SOCKET_PATH into every pane, so an agent with a bash tool can 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. Not hypothetical either: on the recorded workflow, a pi session read its own pane through the socket to check glyph rendering — and surfaced a real bug in herdr pane run while doing it. This is the whole prompt, verbatim:

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.

The last two rules are the hard ones: a shepherd with worker instincts destroys the flock. Rehearse it on a sacrificial workspace before pointing it at real work.

Won't a swarm of cheap agents trash my repo?

Only if you skip the expensive part. The swarm is cheap; the plan is the whole game. First, your smartest model at max thinking runs this — and you argue with the output until no two workers touch the same file:

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.

Then each brief fans out as a direct process — argv launch, no shell, no typed command, no startup race — into a visible, interruptible pane. Captured from my running server the day before this workshop:

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

One orchestrator, three workers, each confined to its own directory. Dead workers are socket events (pane.exited), not screens that stopped changing. And the keeper above composes: one pane's pi babysits the whole swarm.

And if I don't run your Karabiner config?

Then none of the Esc chords exist — they're my machine's config, not herdr features, and I'd rather tell you that than have you think the tool is broken. Herdr's portable bindings work everywhere: cmd+d splits, cmd+alt+arrows pane focus, a tmux-style ctrl+b leader. More importantly, everything the agents do here — recon, keeper, swarm — needs zero keybindings. The socket CLI is the floor; the keyboard layer is just how a human stays fast on top of it.

Source references