Herding Claude: a real herdr setup, end to end

# herdr config — only overrides; everything else keeps herdr defaults.
# Full annotated defaults: herdr --default-config
# Apply changes to the running server: herdr server reload-config

onboarding = false

[keys]
# Project-hopping muscle memory ported from zellij (Alt+[ / Alt+] there
# switched project tabs; here projects are workspaces).
# Requires Ghostty's macos-option-as-alt = true (already set).
previous_workspace = "alt+["
next_workspace = "alt+]"
# Jump straight to workspace N.
switch_workspace = "prefix+shift+1..9"
# zellij's Alt layer: move pane focus without the prefix.
focus_pane_left = "alt+h"
focus_pane_down = "alt+j"
focus_pane_up = "alt+k"
focus_pane_right = "alt+l"

# Port of the claude.kdl hunk pane: prefix+alt+d opens a temporary
# pane with the hunk diff viewer, closes when you quit it.
# (Optional upgrade once on 0.7.4+: type = "popup" with width/height
# floats it over the layout instead of splitting.)
[[keys.command]]
key = "prefix+alt+d"
type = "pane"
command = "hunk diff"

[ui]
# iPhone/Termius portrait can exceed 64 cols with a small font; 72 keeps
# the single-column mobile layout kicking in reliably on the phone.
mobile_width_threshold = 72
# Agents needing attention float to the top of the sidebar instead of
# staying grouped under their workspace.
agent_panel_sort = "priority"

[ui.toast]
# "terminal" escalates agent-needs-attention popups to the OUTER terminal
# (Ghostty -> real macOS notifications) and works over SSH. Popups are
# suppressed for the active tab, so only background work alerts you.
delivery = "terminal"

[experimental]
# Restore recent pane screen contents after a full server restart (stored
# in session-history.json). Trade-off: scrollback may contain secrets at
# rest; acceptable on this single-user FileVault Mac.
pane_history = true

#!/usr/bin/env bash
# herdr-spaces — idempotently bootstrap herdr workspaces (safe to re-run; each
# workspace is keyed by its label and created only if absent).
set -euo pipefail

# ---- config (edit these) --------------------------------------------------
MAX_CLIENTS=10                              # keep the top-N frecent clients
EXTRA_CLIENTS=("$HOME/Projects/side-project") # always-include absolute paths
EXCLUDE=()                                  # client dir basenames to skip
CLIENT_ROOT="$HOME/Clients"                # frecency root (zoxide)
FLAGSHIP="$HOME/Projects/flagship"
CLAUDE_CMD="${HERDR_SPACES_CLAUDE:-claude}" # override for testing, e.g. a stub
created=0; skipped=0

# ---- helpers --------------------------------------------------------------
die() { echo "herdr-spaces: $*" >&2; exit 1; }
workspace_exists() {  # $1=label
  herdr workspace list | jq -e --arg l "$1" 'any(.result.workspaces[]?; .label==$l)' >/dev/null
}
workspace_id_for() {  # $1=label -> workspace_id | ""
  herdr workspace list | jq -r --arg l "$1" 'first(.result.workspaces[]? | select(.label==$l) | .workspace_id) // empty'
}
first_tab_id() {      # $1=workspace_id -> lowest-numbered tab_id | ""
  herdr tab list --workspace "$1" | jq -r '((.result.tabs? // []) | sort_by(.number))[0].tab_id // empty'
}
tab_id_for_label() {  # $1=workspace_id $2=label -> tab_id | ""
  herdr tab list --workspace "$1" | jq -r --arg l "$2" 'first(.result.tabs[]? | select(.label==$l) | .tab_id) // empty'
}
pane_id_for_tab() {   # $1=workspace_id $2=tab_id -> pane_id | ""
  herdr pane list --workspace "$1" | jq -r --arg t "$2" 'first(.result.panes[]? | select(.tab_id==$t) | .pane_id) // empty'
}
is_excluded() { local x; for x in "${EXCLUDE[@]}"; do [[ "$1" == "$x" ]] && return 0; done; return 1; }
run_in_tab() {        # $1=workspace_id $2=tab_label $3=command — type command into that tab's shell
  local tid pid
  tid=$(tab_id_for_label "$1" "$2"); [[ -n "$tid" ]] || { echo "  ! no tab '$2' in $1" >&2; return; }
  pid=$(pane_id_for_tab "$1" "$tid"); [[ -n "$pid" ]] || { echo "  ! no pane for '$2' in $1" >&2; return; }
  herdr pane run "$pid" "$3" >/dev/null
}
ensure_client() {     # $1=dir $2=label $3=note
  if is_excluded "$2"; then echo "skip $2 (excluded)"; skipped=$((skipped+1)); return; fi
  [[ -d "$1" ]] || { echo "skip $2 (missing dir)"; skipped=$((skipped+1)); return; }
  if workspace_exists "$2"; then echo "skip $2 (exists)"; skipped=$((skipped+1)); return; fi
  echo "create workspace $2 ($3)"
  herdr workspace create --cwd "$1" --label "$2" --no-focus >/dev/null; created=$((created+1))
}
setup_ws() {          # $1=label $2=tab1 $3=cmd1 $4=tab2 $5=cmd2 — create the 2-tab ws only if absent
  local wid tid
  if [[ ! -d "$FLAGSHIP" ]] || workspace_exists "$1"; then
    echo "skip $1 (exists or missing)"; skipped=$((skipped+1)); return
  fi
  echo "create workspace $1"
  herdr workspace create --cwd "$FLAGSHIP" --label "$1" --no-focus >/dev/null; created=$((created+1))
  wid=$(workspace_id_for "$1"); [[ -n "$wid" ]] || { echo "  ! lost $1 after create" >&2; return; }
  tid=$(first_tab_id "$wid")
  if [[ -n "$tid" ]]; then
    herdr tab rename "$tid" "$2" >/dev/null || echo "  ! rename failed in $1" >&2
  fi
  sleep 1; run_in_tab "$wid" "$2" "$3"
  herdr tab create --workspace "$wid" --cwd "$FLAGSHIP" --label "$4" --no-focus >/dev/null \
    || { echo "  ! tab create failed in $1" >&2; return; }
  sleep 1; run_in_tab "$wid" "$4" "$5"
}

# ---- preflight ------------------------------------------------------------
command -v jq    >/dev/null 2>&1 || die "jq not found"
command -v herdr >/dev/null 2>&1 || die "herdr not found"
# No pipes here: grep -q closes the pipe early and herdr panics on
# SIGPIPE (exit 101), which pipefail then propagates. Capture instead.
status_out="$(herdr status 2>/dev/null)" || true
[[ "$status_out" == *"status: running"* ]] || die "no running herdr server"
if [[ "$status_out" == *"compatible: no"* ]]; then
  die "client/server protocol mismatch — restart the herdr server first (herdr server stop; herdr)"
fi

# ---- 1. client workspaces, ranked by summed zoxide frecency ---------------
client_lines=()
if command -v zoxide >/dev/null 2>&1; then
  mapfile -t client_lines < <(
    zoxide query -ls 2>/dev/null | awk -v root="$CLIENT_ROOT/" '
      { line=$0; sub(/^[ \t]*[^ \t]+[ \t]+/,"",line)          # drop score, keep the path
        if (index(line,root)==1) {
          rest=substr(line,length(root)+1); s=index(rest,"/")
          c=(s>0)?substr(rest,1,s-1):rest                     # first component = client dir
          if (c!="") sum[c]+=($1+0) } }
      END { for (c in sum) printf "%.1f\t%s\n", sum[c], c }' \
    | sort -rn | head -n "$MAX_CLIENTS"
  )
else
  echo "herdr-spaces: zoxide not found, skipping frecency clients" >&2
fi
seen=()
for line in "${client_lines[@]}"; do
  score=${line%%$'\t'*}; client=${line#*$'\t'}
  ensure_client "$CLIENT_ROOT/$client" "$client" "score $score"; seen+=("$CLIENT_ROOT/$client")
done

# ---- 2. pinned extra clients (dedup against the frecency set) -------------
for dir in "${EXTRA_CLIENTS[@]}"; do
  dup=0; for s in "${seen[@]}"; do [[ "$s" == "$dir" ]] && { dup=1; break; }; done
  [[ $dup -eq 1 ]] && continue
  ensure_client "$dir" "$(basename "$dir")" "pinned"
done

# ---- 3 & 4. flagship dev + deploy ------------------------------------------
# NOTE: prompts below are typed into the pane wrapped in single quotes —
# keep apostrophes out of them (use em dashes / rewording instead).
setup_ws "flagship dev" research "$CLAUDE_CMD" eng "$CLAUDE_CMD"
deploy_cmd="$CLAUDE_CMD 'You are the deploy operator for this product. Read the Redeploying section of CLAUDE.md. Wait for my instructions — when I say deploy, run the smoke check (bash tests/local_smoke.sh) first, then bash deploy/redeploy.sh, then verify healthz. You also handle provisioning new boxes when I ask.'"
monitor_cmd="$CLAUDE_CMD 'You are the monitor for this product. Check https://yourapp.example/healthz, systemd unit status on the app box (ssh root@yourbox), and recent logs. Give me a one-screen health summary now, then wait for my instructions. Read-only: never restart or deploy anything.'"
setup_ws "flagship deploy" deploy "$deploy_cmd" monitor "$monitor_cmd"

# ---- 5. scratch (skip if a "scratch" or the current "~" workspace exists) --
if workspace_exists scratch || workspace_exists "~"; then
  echo "skip scratch (exists)"; skipped=$((skipped+1))
else
  echo "create workspace scratch"
  herdr workspace create --cwd "$HOME" --label scratch --no-focus >/dev/null; created=$((created+1))
fi

echo "$created created, $skipped skipped"

# ---------------------------------------------------------------------------
# Pin a client:     add its absolute path to EXTRA_CLIENTS, e.g.
#                     EXTRA_CLIENTS=("$HOME/Projects/side-project" "$HOME/Projects/x")
# Exclude a client: add its directory basename to EXCLUDE, e.g. EXCLUDE=("OldClient").
# Show more/fewer frecent clients: change MAX_CLIENTS at the top.

/opt/homebrew/bin/mosh-server new -s -c 256 -l LANG=en_US.UTF-8