{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-visible-workspaces-worked-example",
  "slug": "visible-workspaces-worked-example",
  "title": "Visible workspaces for agents and swarms — worked example",
  "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Team practice",
  "tags": [
    "visible-workspaces",
    "examples"
  ],
  "sources": [
    {
      "label": "Visible workspaces for agents and swarms — worked example",
      "url": "https://summit-inlet-kxyf.here.now/replay.html"
    }
  ],
  "sourceUnits": [
    "06-pi-herdr-ghostty/replay.html#The session, replayed"
  ],
  "collection": "factory",
  "categoryId": "team-practice",
  "wordCount": 1103,
  "url": "/topics/factory-visible-workspaces-worked-example/",
  "markdownUrl": "/markdown/factory-visible-workspaces-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-visible-workspaces-worked-example.json",
  "headings": [
    {
      "id": "the-session-replayed",
      "text": "The session, replayed",
      "level": 2
    }
  ],
  "markdown": "# Visible workspaces for agents and swarms — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session, replayed\n\nYou\n\nRead my `~/.config/karabiner.edn` and tell me what the Ghostty-scoped rules actually do.\n\nAgent\n\nRead the file (goku/EDN format). Three rule groups fire only while Ghostty is frontmost:\n\n``` text\n~/.config/karabiner.edn — Ghostty-scoped rules\n\n:applications          :ghostty [\"com.mitchellh.ghostty\"]\n\n\"Ghostty: Escape Mode Herdr actions\"\n  hold Esc + Z/F/O/E/R/P/Y/L/X/N/Space -> internal Ctrl+Alt chords\n  (tap Esc alone still sends Escape)\n\n\"Ghostty: Herdr workspace shortcuts\"\n  tap Left Ctrl -> herdr leader (Ctrl+B)\n  tap Left Cmd  -> workspace switcher\n\n\"Comma Mode\" simlayer (works anywhere)\n  , + letter -> herdr-focus-or-open-workspace \"<Label>\" \"<dir>\"\n```\n\nNotable: the Esc chords don't run any command themselves. They only emit synthetic keystrokes like `Ctrl+Alt+Z`.\n\nFirst beat is reconnaissance. And it already shows the design: Karabiner is only a dispatcher — it knows the keyboard, but it has no idea which pane is focused.\n\nYou\n\nChords going where? Find whatever is listening for `Ctrl+Alt+Z`.\n\nAgent\n\nSearched `~/.config/herdr/config.toml`. Every chord Karabiner emits has a matching `[[keys.command]]` binding, and the config states the handshake in its own comment:\n\n``` text\n~/.config/herdr/config.toml — [[keys.command]] entries (abridged)\n\n# Karabiner emits these internal chords only while Ghostty is frontmost;\n# Herdr supplies the exact focused inner pane.\n\nctrl+alt+z        shell  herdr-escape zed          # cwd in Zed\nctrl+alt+f        shell  herdr-escape finder       # cwd in Finder\nctrl+alt+o        shell  herdr-escape smart        # URL / file:line / cwd\nctrl+alt+r        shell  herdr-escape repo         # GitHub repo in browser\nctrl+alt+p        shell  herdr-escape pr           # PR for current branch\nctrl+alt+shift+l  pane   herdr-escape pane-search  # search ALL pane output\n```\n\nThe `pane-search` binding is `type = \"pane\"`: it opens a temporary pane, searches every pane's recent output, and picking a hit focuses the pane that printed it. The pane then closes — by design.\n\nThe whole keyboard story in one comment: Karabiner knows the keyboard, herdr knows the focused pane, and the internal Ctrl+Alt chords are how they shake hands. Neither layer could do this alone. A liftable 3-chord version of both files is in the [full guide](https://summit-inlet-kxyf.here.now/index.html).\n\nYou\n\nEnough configs. Show me what the socket will actually tell a script — read-only.\n\nAgent\n\nRan the recon set against the live server (herdr 0.7.3, protocol 16):\n\n``` text\nherdr status\nherdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, \"\\(.pane_count) panes\"] | @tsv'\nherdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'\nherdr agent list\n```\n\n``` text\n1  script-kit-gpui     idle     5 panes\n2  pi                  idle     1 panes\n3  mdflow              idle     2 panes\n4  pushing-boundaries  working  4 panes\n5  pi-herdr-subagents  working  1 panes\n6  Prompt Builder      working  3 panes\n```\n\nThe `working`/`idle` states are reported by the agents' own herdr integrations over the socket — not scraped from the screen.\n\nThis is the answer to \"why herdr\": the entire workspace → tab → pane model is a JSON socket API. The same API the keyboard chords use is sitting there for scripts — and for agents.\n\nYou\n\nProve that last part. You're running inside one of these panes — read your own screen.\n\nAgent\n\nHerdr injected `HERDR_PANE_ID` and `HERDR_SOCKET_PATH` into my environment, so:\n\n``` text\nherdr pane read \"$HERDR_PANE_ID\" --lines 20\n```\n\n``` text\n… the last 20 lines of this pane: your instruction above,\nmy own output, this very command echoing back.\nThe agent is reading the screen it is printing to.\n```\n\nNot hypothetical: in a prior session (the recorded workflow), a pi session used exactly this self-read to check glyph rendering in its own pane — and surfaced a real bug in `herdr pane run` while doing it. Self-inspection finds real bugs.\n\nYou\n\nWorkspace 4 said `working` with 4 panes. What's actually in there?\n\nAgent\n\nListed its panes. It's a live swarm — one orchestrator, three workers, each confined to its own directory:\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\nEach worker was fanned out as a direct process — argv launch, no shell, no typed command, no startup race:\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\nThree workers, zero shared files, no ordering between them — that shape is not luck. It comes from planning the decomposition with the smartest model first; the planning prompt is in the [full guide](https://summit-inlet-kxyf.here.now/index.html)'s prompt library. The swarm is the cheap part.\n\nYou\n\nLast thing. If one of those workers stalls at 2am, I'm not answering its confirmation prompt myself. One pane's agent should keep the rest alive. Write me that prompt.\n\nAgent\n\nThe keeper. Paste it into a pi session (or any agent with a bash tool) running inside a herdr pane, in the workspace to supervise:\n\n``` text\nYou are the keeper of this herdr session. Other panes in this workspace are\nrunning coding agents. Your job is to keep them all moving until every task\nis done. Loop:\n\n1. `herdr agent list` — enumerate sibling agents and their states. Ignore\n   your own pane (`$HERDR_PANE_ID`).\n2. For each sibling that is `blocked` or has been `idle` while its task is\n   unfinished:\n   - `herdr agent read <target> --lines 40` to see what it last printed.\n   - If it is waiting on a confirmation prompt, answer it with\n     `herdr agent send <target> \"<the answer>\"`.\n   - If it crashed or its pane shows a shell prompt, relaunch its task with\n     `herdr pane run <pane_id> \"<original command>\"`.\n   - If it is stuck in a loop, interrupt (send Ctrl+C via\n     `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more\n     precisely.\n3. Instead of polling in a tight loop, block on\n   `herdr wait agent-status <pane_id> --status idle --timeout 600000`\n   for the pane most likely to finish next.\n4. After every intervention, log one line: pane id, what you saw, what you did.\n5. Stop when every sibling is idle AND its last output shows its task\n   completed. Then print a table: pane → task → outcome.\n\nNever close panes. Never start new work. You are a shepherd, not a worker.\n```\n\nEvery verb in it is one the session already used read-only, plus three writers: `agent send`, `pane run`, `pane send-keys`. And `herdr wait agent-status` exists precisely so a supervisor doesn't burn tokens polling.\n\nThe landing. The two hard rules — never close panes, never start new work — exist because a shepherd with worker instincts destroys the flock. Rehearse it on a sacrificial workspace before pointing it at real work; the full caveats live in the [full guide](https://summit-inlet-kxyf.here.now/index.html)'s appendix."
}
