---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-visible-workspaces"
title: "Visible workspaces for agents and swarms"
---

# Visible workspaces for agents and swarms

Expose pane state, separate execution from verification, and supervise bounded independent work.

## Related working material

- [Visible workspaces for agents and swarms — prompts and exercises](/topics/factory-visible-workspaces-practice/)
- [Visible workspaces for agents and swarms — questions and tradeoffs](/topics/factory-visible-workspaces-questions/)
- [Visible workspaces for agents and swarms — worked example](/topics/factory-visible-workspaces-worked-example/)

## TL;DR

- A terminal stack whose pane model is fully scriptable over a unix socket — by your keyboard, your scripts, and your agents.
- You walk away with a read-only recon command set, a complete 3-chord keyboard config, and the keeper prompt: an agent that keeps other agents moving.
- The one move: paste the keeper prompt into pi running inside a herdr pane. It answers stuck prompts, restarts crashes, and unsticks its siblings.

 Have your agent set this up — paste this into it:

``` text
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.
```

## 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 / F      | Open the focused pane's cwd in Zed / Finder                   |
| O          | Smart open: URL, file:line reference, or cwd — whichever fits |
| E          | Open the latest file:line reference in Zed                    |
| R / P      | Open the current GitHub repo / the PR for the current branch  |
| Y          | Copy pane/repo context                                        |
| L          | Pick a URL from pane output (temporary picker pane)           |
| Space      | Search ALL pane output; picking a hit focuses that pane       |
| X / N      | Open Codex / Prompt Builder in a new pane                     |
| Return     | Zoom 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`.

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

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

``` text
;; 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 the recorded workflow, 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:

``` text
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:

``` text
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 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, version-specific snapshot). 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.

## Operating practice

### Keep wrappers thin and work visible

#### What to notice

Remove flag memorization while keeping the **real command**, task state, logs, and **verification** inspectable.

#### Try this

Create three visible responsibilities: execution, **verification**, and logs or status.

> “Kind of forget the flags, especially if you're someone jumping back and forth between the different harnesses.”

John Lindquist · [01:23:01](https://proud-anchor-53zn.here.now/watch.html?t=4981#recording-player)

#### Concept

A wrapper earns its place when it prevents a repeated mistake and remains easy to trace. More panes do not create understanding. Add a surface only when it represents an independently observable responsibility.

#### Reflection

The presenter’s terminal stack is an example. The reusable practice is consistent launch behavior and visible state.

**Recording evidence:** listen at 01:21:23.

> “The beauty of owning your own tools is you can have them test themselves, and write themselves, and tackle themselves.”

John Lindquist · [01:37:37](https://proud-anchor-53zn.here.now/watch.html?t=5857#recording-player)

[Open Custom zsh Functions](https://sacred-ritual-w7as.here.now/)[Open Pi, Herdr, and Ghostty](https://summit-inlet-kxyf.here.now/)

#### Links shared for this topic

- [Herdr](https://herdr.dev) — A workspace surface for seeing parallel agent activity.
- [Linear](https://linear.app/) — Issue and project tracking referenced during workflow discussion.
- [Claudex](https://github.com/johnlindquist/claudex) — A proxy and launcher experiment for coding-agent sessions.
- [Cloudflare AI code review](https://blog.cloudflare.com/ai-code-review/) — A published account of AI-assisted review at production scale.

[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=4883#q1-launcher-workspaces)

## Original references

- [Visible workspaces for agents and swarms](https://summit-inlet-kxyf.here.now/)
- [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)
