herdr-workspace

Bootstrap script that creates Talbot’s standard Herdr workspace/tab layout (mirrors ~/.tmux/work.sh’s window set) in one idempotent run.

Configuration — changing tabs or defaults (read this first)

No restart, ever — of herdr, WSL, or Windows. Every change below is a live CLI call while herdr keeps running. Editing TABS alone does nothing by itself — it’s only a template; step 2 is what actually moves a tab. Skipping step 2 is the #1 way this looks broken.

Step 1 — edit the template. TABS array in ~/utils/herdr-workspace.sh, one line per tab: "label|cwd|launch_claude" (launch_claude=1 auto-runs claude in that tab). This only defines what a future tab-create looks like — it does not touch any tab that already exists.

Step 2 — apply it, live. One command, from Core tab, always:

~/utils/herdr-workspace.sh --sync

Closes every non-Core tab and recreates all of them fresh from TABS, in TABS’ order — whatever you changed (added, removed, relabeled, re-cwd’d, reordered), this one command makes live match the file, every time. No restart of herdr, WSL, or Windows.

Run it from Core (or any idle tab) — never from a tab you’re actively working in. It refuses and lists the offending tab if any non-Core tab has agent_status: working/blocked (an active Claude/agent session) — that includes the tab you’re typing in right now if you’re running it from inside one.
Plain ~/utils/herdr-workspace.sh (no flag, alias herdr-work) is the gentler, non-destructive sibling: only adds a tab that’s missing, never touches or reorders existing ones. That’s what runs automatically on every new Ubuntu terminal — not what you want after editing TABS.
~/utils/herdr-reorder-core-first.sh is now a special case of --sync (only fires when Core isn’t first) — kept for the narrow case where nothing else about the layout changed.

Location

~/utils/herdr-workspace.sh (WSL-side, per Utility script placement rule)

Quick Start

herdr-work   # alias, see ~/.bashrc
# or
~/utils/herdr-workspace.sh

Creates (or focuses, if it already exists) workspace work with tabs, in order: Core (first tab, per Talbot), SDC (auto-launches Claude Code), KB-OS, mBR, monorepo, utils, web-deploy, research (~/hyperresearch, the only place /hyperresearch may be started; added 2026-09-23). Herdr’s tab = tmux’s window; herdr’s workspace = tmux’s session.

Live tab set/order can drift from this list — a tab added manually, or a live reorder done via close/recreate (see Configuration above), isn’t reflected here until this note is updated; herdr tab list --workspace <id> is the source of truth for current state.

~/.bashrc’s Herdr auto-start block runs this script (ensure-exists + focus “work”) before exec herdr, so every new Ubuntu terminal lands directly on “work” instead of the default ”~” workspace.

Basic usage

Attach/launch: herdr (auto-run by ~/.bashrc on every new Ubuntu terminal, after this bootstrap script)
Server status: herdr status
Kill server (test config.toml changes without rebooting Windows): herdr server stop — next herdr invocation starts a fresh server and re-reads config.toml
Reload config.toml only, no restart: herdr server reload-config
Full tab/workspace CLI: herdr tab <list|create|get|focus|rename|close>, herdr workspace <list|create|get|focus|rename|close> (full reference: Core/IT/Utils/External/Utilities.md → Herdr)

Static config (keybindings/theme/UI): ~/.config/herdr/config.toml — reload via herdr server reload-config, unrelated to tabs
Live session state (workspaces/tabs/pane cwd): ~/.config/herdr/session.json — server-persisted, never hand-edit while running. Change it only via the CLI/hotkeys described in Configuration above.
Full tool reference (install, plugins, integration): Core/IT/Utils/External/Utilities.md → Herdr
AI dept pointer (why Ubuntu terminals use Herdr, not tmux): Core/AI/Notes/WSL-Windows Config.md → Herdr (Ubuntu terminal multiplexer)

Scope / gotchas

Depends on herdr being installed (see Core/IT/Utils/External/Utilities.md → Herdr).
Separate from tmux — ~/.tmux/work.sh is untouched; run one or the other per Ubuntu window, not both in the same window. Check block order in ~/.bashrc: an earlier exec-ing auto-start block (e.g. an old tmux block) silently prevents a later one from ever running — the shell never reaches it. Confirmed 2026-08-04: a leftover tmux auto-start block above the Herdr block caused “Ubuntu still launches tmux” even after Herdr’s block was enabled.
Must be run inside a live herdr session (needs the server socket) — won’t work from a plain non-herdr shell.
If a --cwd path doesn’t exist, herdr silently falls back to $HOME instead of erroring — worth spot-checking new tabs’ cwd after any repo restructure.
Template tab removed 2026-08-12 (Talbot: final config simplification).
KB-mBR/Acct-HST → SDC/mBR 2026-08-24, canonical set now 7: Core, SDC, KB-OS, mBR, monorepo, utils, web-deploy.
--sync flag added 2026-08-24 — closes+recreates every non-Core tab from TABS in one command (see Configuration above), so any TABS edit (add/remove/relabel/re-cwd/reorder) applies with a single command instead of a different manual CLI call per kind of change. Verified 2026-08-24: refuses correctly when run from a tab with an active agent session (tested against this session’s own working utils tab); full apply run still needs verifying from an actually-idle tab.