diff --git a/onboarding/MAINTAINING.md b/onboarding/MAINTAINING.md index e238fb9..4d2b8d7 100644 --- a/onboarding/MAINTAINING.md +++ b/onboarding/MAINTAINING.md @@ -14,7 +14,7 @@ not by copying secrets or by being granted access to the PI's machines. ## Architecture (the mental model the kit assumes) - **One real environment, on Linux** (the member's office PC). The agent stack — Claude - Code, agent-skills, superpowers, tmux — lives here and only here. + Code, agent-skills, superpowers, and a multiplexer (tmux or Herdr) — lives here and only here. - **Laptops are dual-role ("mixed by purpose"):** thin client (ssh/mosh + `tmux attach`) into the Linux box for heavy work, *plus* native Obsidian for notes. A laptop needs only tailscale + a terminal + Obsidian. @@ -33,6 +33,7 @@ not by copying secrets or by being granted access to the PI's machines. | `onboarding/vault-structure.md` | DRGScripts | Vault tree + scaffold + which seeds go where. | The vault layout changes. | | `onboarding/vault-seeds/**` | DRGScripts | Real files copied into the member's vault (operating manual, wiki index, cheatsheets, tmux.conf). | The seeds drift from the PI's (sanitized) originals. | | `onboarding/dotfiles/tmux.conf` | DRGScripts | The group tmux config. | The PI's `~/.tmux.conf` changes. | +| `onboarding/dotfiles/herdr-config.toml` | DRGScripts | The group Herdr config (for members who use Herdr instead of/besides tmux). | The PI's `~/.config/herdr/config.toml` changes. | | `ARC/CLAUDE.md` | DRGScripts | Existing ARC project guide — referenced, not duplicated. | (Maintained independently.) | ## Decisions & rationale @@ -47,7 +48,9 @@ not by copying secrets or by being granted access to the PI's machines. | Statusline | the **simple context-% script**, not the PI's `~/agents` auto-handoff variant | Self-contained; no extra infra to stand up. | | Seeds | **sanitized**, real files under `vault-seeds/` | Easy `cp` into place; the PI's real remote-dev note (tailnet IPs, VPN endpoint, cluster/exit-node config) is excluded — a generic `Remote Dev — Pattern` replaces it. | | First pass | **Claude Code only** | Smaller surface; the deferred list below grows it later. | -| Silent-stall detection | **cc-watchdog** (`onboarding/watchdog/`): timer-driven dead-man's switch, not hook-driven heuristics | CC-hook watchers only wake at turn ends, so they share the session's blind spot (a 36 h TA die-out in 2026-07 motivated this). Deadlines declared by the session itself make false positives ~zero (a 2.75 h quiet suite run is legitimate work); a 6 h notify-only backstop covers sessions that never declared. Unlike the PI-local auto-handoff/Phoenix stack, this ships to members: standalone (tmux + coreutils + systemd user timer + one Slack webhook). | +| Multiplexer | **Herdr recommended; tmux also supported** (ONBOARDING step 7) | Herdr is agent-state-aware (mouse-first sidebar showing each agent's live state), which the cc-watchdog guard and the agent-skills auto-handoff/Phoenix watchers gate on natively — so it's the recommended default. tmux stays fully supported for members who deliberately prefer a keyboard-first multiplexer. | +| Herdr `settings.json` hook | **member runs `herdr integration install claude`** | Unlike the PI's literal settings.json, the herdr agent-state hook is generated by the installer into the member's own `~/.claude/settings.json` — no personal infra to copy. | +| Silent-stall detection | **cc-watchdog** (`onboarding/watchdog/`): timer-driven dead-man's switch, not hook-driven heuristics | CC-hook watchers only wake at turn ends, so they share the session's blind spot (a 36 h TA die-out in 2026-07 motivated this). Deadlines declared by the session itself make false positives ~zero (a 2.75 h quiet suite run is legitimate work); a 6 h notify-only backstop covers sessions that never declared. Unlike the PI-local auto-handoff/Phoenix stack, this ships to members: standalone (tmux/Herdr + coreutils + systemd user timer + one Slack webhook). | ## Deferred — "later" (and how to un-defer) diff --git a/onboarding/ONBOARDING.md b/onboarding/ONBOARDING.md index 9425f94..a1bc4bf 100644 --- a/onboarding/ONBOARDING.md +++ b/onboarding/ONBOARDING.md @@ -10,9 +10,9 @@ ## What you're building - **One real environment, on your office Linux PC** — the agent stack (Claude Code, - agent-skills, superpowers, tmux) lives here and only here. + agent-skills, superpowers, Herdr) lives here and only here. - **Your laptop (Win/Mac) is a thin client + Obsidian** — you SSH/mosh into the Linux PC - and `tmux attach`, and you run Obsidian locally on the Dropbox-synced vault. + and attach your Herdr session (or tmux), and you run Obsidian locally on the Dropbox-synced vault. - This is **your own independent setup**: your own Tailscale tailnet, your own Obsidian vault, your own Claude account. Nothing here grants access to anyone else's machines. @@ -77,12 +77,43 @@ folders there; those are **git-ignored** — don't commit them. Update gstack la "use `/browse` for all web browsing" rule) comes from the CLAUDE.global.md merge in step 8, so you don't add it by hand here. -### 7. tmux config +### 7. Terminal multiplexer — Herdr (tmux also supported) +A multiplexer keeps your panes (and long agent sessions) alive across +disconnects, and is what the cc-watchdog guard (step 13) drives. +**Use [Herdr](https://herdr.dev)** — it's the group's recommended default because +it's agent-aware (shows each agent's live state in a sidebar) and the cc-watchdog +guard and the PI's watchers gate on that state natively. tmux is also fully +supported if you deliberately prefer a keyboard-first, ubiquitous multiplexer. + +**Herdr** (recommended): +```bash +curl -fsSL https://herdr.dev/install.sh | sh # installs the `herdr` binary +herdr integration install claude # wires the agent-state hook into ~/.claude/settings.json +mkdir -p ~/.config/herdr # ensure the config dir exists before copying +cp /onboarding/dotfiles/herdr-config.toml ~/.config/herdr/config.toml +``` +The `/herdr` control skill ships in the agent-skills clone from step 5, so +Claude Code can drive panes/tabs directly. Launch with `herdr`, then start +`claude` inside a pane; detach with `prefix+q` (prefix is `ctrl+b`), `prefix+?` +lists all bindings. + +**tmux** (alternative — if you deliberately prefer it): ```bash cp /onboarding/dotfiles/tmux.conf ~/.tmux.conf ``` Prefix is `C-a`. (Optional persistence plugins need `tpm` — see the comments in the file.) +The cc-watchdog stall-guard (step 13) works under both Herdr and tmux. (The PI's optional +auto-handoff / Phoenix watchers — deferred for members, see MAINTAINING — are +likewise multiplexer-aware if you enable them later.) + +Optional remote-attach aliases (add to `~/.bashrc`), to connect and attach on a +workstation named `ol`: +```bash +alias olh='herdr --remote ol' # Herdr (needs herdr installed on ol) +alias olt='ssh -t ol "tmux attach || tmux new"' # tmux +``` + ### 8. Global CLAUDE.md Merge [CLAUDE.global.md](./CLAUDE.global.md) into your `~/.claude/CLAUDE.md` (have Claude Code merge it, preserving any lines you've already added). Fix the **Obsidian Vault path** @@ -218,7 +249,12 @@ rules are the prevention. Details: `onboarding/watchdog/README.md`. ``` (macOS: skip — use the native Terminal; `brew install mosh` if you want mosh.) 2. **Tailscale** — install the GUI app, sign in to the same tailnet, confirm *Connected*. -3. **Terminal into the Linux PC** (run agents on the remote, never the laptop): +3. **Terminal into the Linux PC** (run agents on the remote, never the laptop). With Herdr + (recommended) one command attaches your remote session — start `claude` inside a pane: + ```bash + herdr --remote # your user + tailnet host name; needs herdr on both ends + ``` + Prefer tmux? Attach the classic way instead: ```bash ssh @ # your user + tailnet host name tmux attach -t cc || tmux new -s cc @@ -236,7 +272,8 @@ rules are the prevention. Details: `onboarding/watchdog/README.md`. ## C. Verification smoke test - [ ] `tailscale status` shows your tailnet and this host. -- [ ] From the laptop: `ssh`/`mosh` into the Linux PC, `tmux attach` works. +- [ ] From the laptop: `ssh`/`mosh` into the Linux PC and attach your session + (`herdr --remote`, or `tmux attach`) works. - [ ] A Claude Code session lists the gstack skills from step 6 (type `/` and look for `/browse`, `/review`, `/ship`, …); superpowers loads. - [ ] The status line shows the model name + context-window %. diff --git a/onboarding/dotfiles/herdr-config.toml b/onboarding/dotfiles/herdr-config.toml new file mode 100644 index 0000000..de7de1d --- /dev/null +++ b/onboarding/dotfiles/herdr-config.toml @@ -0,0 +1,26 @@ +# Herdr config — sensible defaults for autonomous multi-agent work. +# Place at ~/.config/herdr/config.toml. Herdr runs fine without it; these are +# only deltas from the built-in defaults. See every knob: `herdr --default-config`. +# Reload into a running server after edits: `herdr server reload-config`. + +[ui] +# Float blocked / needs-attention agents to the top of the sidebar instead of +# grouping by space. Handy when several agents run at once. +agent_panel_sort = "priority" + +[ui.toast] +# Notify when a background agent changes state (done / blocked). "terminal" +# routes the notification to the terminal you're currently attached to, so it +# reaches you even when you attach remotely over SSH (unlike "system", which +# fires on the host's own desktop). +delivery = "terminal" + +[experimental] +# Preserve pane screen contents across a full server restart, so a long run's +# output isn't lost if the server bounces. +pane_history = true + +[advanced] +# Long autonomous sessions emit a lot of output — keep more scrollback for +# review (50MB, up from the 10MB default). +scrollback_limit_bytes = 50000000