{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-visible-workspaces-questions",
  "slug": "visible-workspaces-questions",
  "title": "Visible workspaces for agents and swarms — questions and tradeoffs",
  "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Team practice",
  "tags": [
    "visible-workspaces",
    "questions"
  ],
  "sources": [
    {
      "label": "Visible workspaces for agents and swarms — questions and tradeoffs",
      "url": "https://summit-inlet-kxyf.here.now/dialogue.html"
    }
  ],
  "sourceUnits": [
    "06-pi-herdr-ghostty/dialogue.html#The questions the room asks"
  ],
  "collection": "factory",
  "categoryId": "team-practice",
  "wordCount": 1384,
  "url": "/topics/factory-visible-workspaces-questions/",
  "markdownUrl": "/markdown/factory-visible-workspaces-questions.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-visible-workspaces-questions.json",
  "headings": [
    {
      "id": "the-questions-the-room-asks",
      "text": "The questions the room asks",
      "level": 2
    }
  ],
  "markdown": "# Visible workspaces for agents and swarms — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The questions the room asks\n\nWhy not just tmux? It keeps panes alive too.\n\nPersistence 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:\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\nSo the real trick is just Karabiner macros?\n\nHalf 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:\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\nHold on — your live config has a dozen chords. That's a lot of muscle memory.\n\nMine 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:\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\nThirty panes running — how do you find the one that printed the error?\n\nEsc+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:\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\nWhat happens when Ghostty crashes mid-swarm?\n\nNothing 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.\n\n“An agent babysitting other agents” sounds like a demo gimmick.\n\nIt'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:\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\nThe 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.\n\nWon't a swarm of cheap agents trash my repo?\n\nOnly 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:\n\n``` text\nDecompose this project into N independent tasks that can each be completed\nby an agent working alone in its own directory, with no shared files and no\nordering between them. For each task: a directory, a one-paragraph brief, a\ndefinition of done, and the exact command to verify it. If the tasks are\nnot truly independent, redesign the split until they are.\n```\n\nThen 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:\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 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.\n\nAnd if I don't run your Karabiner config?\n\nThen 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."
}
