{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-visible-workspaces",
  "slug": "visible-workspaces",
  "title": "Visible workspaces for agents and swarms",
  "summary": "Expose pane state, separate execution from verification, and supervise bounded independent work.",
  "category": "Team practice",
  "tags": [
    "visible",
    "factory"
  ],
  "sources": [
    {
      "label": "Visible workspaces for agents and swarms",
      "url": "https://summit-inlet-kxyf.here.now/"
    },
    {
      "label": "Companion lesson",
      "url": "https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces"
    }
  ],
  "sourceUnits": [
    "06-pi-herdr-ghostty/index.html#TL;DR",
    "06-pi-herdr-ghostty/index.html#The stack: each layer exposes its state to the one above",
    "06-pi-herdr-ghostty/index.html#Appendix",
    "06-pi-herdr-ghostty/index.html#Two configs shake hands: keyboard to focused pane",
    "06-pi-herdr-ghostty/index.html#The three chords worth stealing (complete config)",
    "06-pi-herdr-ghostty/index.html#The keeper: one agent babysits the rest",
    "06-pi-herdr-ghostty/index.html#Swarms: plan until independent, then fan out",
    "learn.html#q1-launcher-workspaces"
  ],
  "collection": "factory",
  "categoryId": "team-practice",
  "wordCount": 1829,
  "url": "/topics/factory-visible-workspaces/",
  "markdownUrl": "/markdown/factory-visible-workspaces.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-visible-workspaces.json",
  "headings": [
    {
      "id": "related-working-material",
      "text": "Related working material",
      "level": 2
    },
    {
      "id": "tl-dr",
      "text": "TL;DR",
      "level": 2
    },
    {
      "id": "the-stack-each-layer-exposes-its-state-to-the-one-above",
      "text": "The stack: each layer exposes its state to the one above",
      "level": 2
    },
    {
      "id": "two-configs-shake-hands-keyboard-to-focused-pane",
      "text": "Two configs shake hands: keyboard to focused pane",
      "level": 2
    },
    {
      "id": "the-three-chords-worth-stealing-complete-config",
      "text": "The three chords worth stealing (complete config)",
      "level": 3
    },
    {
      "id": "the-keeper-one-agent-babysits-the-rest",
      "text": "The keeper: one agent babysits the rest",
      "level": 2
    },
    {
      "id": "swarms-plan-until-independent-then-fan-out",
      "text": "Swarms: plan until independent, then fan out",
      "level": 2
    },
    {
      "id": "appendix",
      "text": "Appendix",
      "level": 2
    },
    {
      "id": "limits-caveats",
      "text": "Limits & caveats",
      "level": 3
    },
    {
      "id": "operating-practice",
      "text": "Operating practice",
      "level": 2
    },
    {
      "id": "keep-wrappers-thin-and-work-visible",
      "text": "Keep wrappers thin and work visible",
      "level": 3
    },
    {
      "id": "what-to-notice",
      "text": "What to notice",
      "level": 4
    },
    {
      "id": "try-this",
      "text": "Try this",
      "level": 4
    },
    {
      "id": "concept",
      "text": "Concept",
      "level": 4
    },
    {
      "id": "reflection",
      "text": "Reflection",
      "level": 4
    },
    {
      "id": "links-shared-for-this-topic",
      "text": "Links shared for this topic",
      "level": 4
    }
  ],
  "markdown": "# Visible workspaces for agents and swarms\n\nExpose pane state, separate execution from verification, and supervise bounded independent work.\n\n## Related working material\n\n- [Visible workspaces for agents and swarms — prompts and exercises](/topics/factory-visible-workspaces-practice/)\n- [Visible workspaces for agents and swarms — questions and tradeoffs](/topics/factory-visible-workspaces-questions/)\n- [Visible workspaces for agents and swarms — worked example](/topics/factory-visible-workspaces-worked-example/)\n\n## TL;DR\n\n- A terminal stack whose pane model is fully scriptable over a unix socket — by your keyboard, your scripts, and your agents.\n- 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.\n- The one move: paste the keeper prompt into pi running inside a herdr pane. It answers stuck prompts, restarts crashes, and unsticks its siblings.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch 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.\n```\n\n## The stack: each layer exposes its state to the one above\n\nThe 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.\n\n**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.\n\nThe 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.\n\n## Two configs shake hands: keyboard to focused pane\n\nKarabiner 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.\"\n\nHolding Esc turns the home row into a herdr command deck:\n\n| Hold Esc + | Action                                                        |\n|------------|---------------------------------------------------------------|\n| Z / F      | Open the focused pane's cwd in Zed / Finder                   |\n| O          | Smart open: URL, file:line reference, or cwd — whichever fits |\n| E          | Open the latest file:line reference in Zed                    |\n| R / P      | Open the current GitHub repo / the PR for the current branch  |\n| Y          | Copy pane/repo context                                        |\n| L          | Pick a URL from pane output (temporary picker pane)           |\n| Space      | Search ALL pane output; picking a hit focuses that pane       |\n| X / N      | Open Codex / Prompt Builder in a new pane                     |\n| Return     | Zoom the focused pane                                         |\n\nOne 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.\n\n### The three chords worth stealing (complete config)\n\nWire 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`.\n\n``` text\n#!/bin/sh\n# Focus-aware chord actions for a herdr session. chmod +x this file.\n# Herdr injects HERDR_ACTIVE_PANE_ID when a [[keys.command]] binding fires.\nset -eu\npane=\"${HERDR_ACTIVE_PANE_ID:-${HERDR_PANE_ID:?run from a herdr binding or pane}}\"\ncwd=\"$(herdr pane get \"$pane\" | jq -r '.result.pane.foreground_cwd')\"\ncase \"${1:-}\" in\n  zed)  zed \"$cwd\" ;;\n  repo) cd \"$cwd\" && gh repo view --web ;;\n  pane-search)\n    herdr pane list | jq -r '.result.panes[].pane_id' | while read -r p; do\n      herdr pane read \"$p\" --source recent-unwrapped --lines 200 2>/dev/null \\\n        | grep -v '^[[:space:]]*$' | sed \"s|^|$p  |\"\n    done | fzf --no-sort --tac | awk '{print $1}' | xargs -r -n1 herdr agent focus ;;\n  *) echo \"usage: herdr-chords zed|repo|pane-search\" >&2; exit 2 ;;\nesac\n```\n\n``` text\n# Karabiner emits these internal chords only while Ghostty is frontmost;\n# Herdr supplies the exact focused inner pane.\n\n[[keys.command]]              # Esc+Z -> open focused pane's cwd in Zed\nkey = \"ctrl+alt+z\"\ntype = \"shell\"\ncommand = \"$HOME/.local/bin/herdr-chords zed\"\n\n[[keys.command]]              # Esc+R -> open focused pane's GitHub repo\nkey = \"ctrl+alt+r\"\ntype = \"shell\"\ncommand = \"$HOME/.local/bin/herdr-chords repo\"\n\n[[keys.command]]              # Esc+Space -> search every pane, jump to the hit\nkey = \"ctrl+alt+shift+l\"\ntype = \"pane\"                 # runs in a temporary pane; it closes after you pick\ncommand = \"$HOME/.local/bin/herdr-chords pane-search\"\n```\n\n``` text\n;; Goku / Karabiner-Elements. Tap Esc = normal Esc.\n;; Hold Esc + key = chord, only while Ghostty is frontmost.\n\n;; under :applications\n:ghostty [\"com.mitchellh.ghostty\"]\n\n;; under :layers — hold-Esc layer; tap still sends Esc\n:escape-mode {:key :escape\n              :params {:basic.to_if_alone_timeout_milliseconds 200\n                       :basic.to_if_held_down_threshold_milliseconds 200}\n              :alone [{:key :escape}]}\n\n;; under :main — the three chords\n{:des   \"Ghostty: Escape Mode Herdr actions\"\n :rules [[:condi :ghostty :escape-mode]\n         [:-z {:key :z :modi [:left_control :left_option]}]       ; Esc+Z\n         [:-r {:key :r :modi [:left_control :left_option]}]       ; Esc+R\n         [:spacebar {:key :l :modi [:left_control :left_option :left_shift]}]]} ; Esc+Space\n```\n\n## The keeper: one agent babysits the rest\n\n\"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.\n\nThis 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.\n\nThe 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.\n\n## Swarms: plan until independent, then fan out\n\nThe 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:\n\n``` text\nherdr agent start learners --cwd ~/dev/proj/sites/learners --split right \\\n  -- bash -lc 'pi -p \"$(cat briefs/learners.md)\"'\n```\n\nThe 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:\n\n``` text\nIllustrative workspace responsibilities:\norchestrator — plan and coordinate\nworker-a — independently scoped audience/site\nworker-b — independently scoped audience/site\nworker-c — independently scoped audience/site\n```\n\nOne 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.\n\n## Appendix\n\n### Limits & caveats\n\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- The `pane run` bug anecdote comes from local conversation-search excerpts, not a replayable transcript. It supports \"this happened that day,\" nothing stronger.\n- Pane-search opens a temporary pane (`type = \"pane\"`) that disappears after selection — by design, not a crash.\n\n## Operating practice\n\n### Keep wrappers thin and work visible\n\n#### What to notice\n\nRemove flag memorization while keeping the **real command**, task state, logs, and **verification** inspectable.\n\n#### Try this\n\nCreate three visible responsibilities: execution, **verification**, and logs or status.\n\n> “Kind of forget the flags, especially if you're someone jumping back and forth between the different harnesses.”\n\nJohn Lindquist · [01:23:01](https://proud-anchor-53zn.here.now/watch.html?t=4981#recording-player)\n\n#### Concept\n\nA 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.\n\n#### Reflection\n\nThe presenter’s terminal stack is an example. The reusable practice is consistent launch behavior and visible state.\n\n**Recording evidence:** listen at 01:21:23.\n\n> “The beauty of owning your own tools is you can have them test themselves, and write themselves, and tackle themselves.”\n\nJohn Lindquist · [01:37:37](https://proud-anchor-53zn.here.now/watch.html?t=5857#recording-player)\n\n[Open Custom zsh Functions](https://sacred-ritual-w7as.here.now/)[Open Pi, Herdr, and Ghostty](https://summit-inlet-kxyf.here.now/)\n\n#### Links shared for this topic\n\n- [Herdr](https://herdr.dev) — A workspace surface for seeing parallel agent activity.\n- [Linear](https://linear.app/) — Issue and project tracking referenced during workflow discussion.\n- [Claudex](https://github.com/johnlindquist/claudex) — A proxy and launcher experiment for coding-agent sessions.\n- [Cloudflare AI code review](https://blog.cloudflare.com/ai-code-review/) — A published account of AI-assisted review at production scale.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=4883#q1-launcher-workspaces)"
}
