From 0f67846c95efd4fe6390919401abef616ea62ba8 Mon Sep 17 00:00:00 2001 From: Sam Rolfe Date: Wed, 29 Jul 2026 12:14:15 +1000 Subject: [PATCH] sam-4screen-desktop 2026-7-29:12:14:15 --- .obsidian/workspace.json | 12 +- 100 inbox/Pi Dashboard.md | 248 ++++++++++++++++++-------------------- 2 files changed, 123 insertions(+), 137 deletions(-) diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index 9750677..75f68b6 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -13,12 +13,12 @@ "state": { "type": "markdown", "state": { - "file": "100 inbox/Pi Subagent Integration.md", + "file": "100 inbox/Pi Dashboard.md", "mode": "preview", "source": true }, "icon": "lucide-file", - "title": "Pi Subagent Integration" + "title": "Pi Dashboard" } } ] @@ -181,10 +181,10 @@ "state": { "type": "file-properties", "state": { - "file": "100 inbox/Pi Subagent Integration.md" + "file": "100 inbox/Pi Dashboard.md" }, "icon": "lucide-info", - "title": "File properties for Pi Subagent Integration" + "title": "File properties for Pi Dashboard" } } ], @@ -209,11 +209,12 @@ }, "active": "29ff3dd1c6bfd474", "lastOpenFiles": [ + "100 inbox/Pi Subagent Integration.md", + "100 inbox/Pi Dashboard.md", "000 daily/Update Install.md", "000 daily/House Family General.md", "000 daily/Daily Notes and To Do.md", "100 inbox/Tools to try with AI.md", - "100 inbox/Pi Dashboard.md", "300 areas/350 AI/Pi Agent Extensions & Skills.md", "100 inbox/AI Design.md", "500 archive/510 Daily/ThinkPad Recommendations.md", @@ -235,7 +236,6 @@ "400 resources/460 Family Archive/Joan Gilligan - Respite.md", "400 resources/460 Family Archive/Harry Trip Lorne Friends.md", "200 projects/260 Build Create Make/Digital Binoculars.md", - "400 resources/410 Web Pages/Website Design AI.md", "500 archive/510 Daily", "300 areas/305 Ideas Businesses", "400 resources/470 Holidays Travel", diff --git a/100 inbox/Pi Dashboard.md b/100 inbox/Pi Dashboard.md index 2fa3bb7..1919c80 100644 --- a/100 inbox/Pi Dashboard.md +++ b/100 inbox/Pi Dashboard.md @@ -1,179 +1,165 @@ -# Pi Dashboard — Architecture Decision Record +# Pi Dashboard — Decisive Build Plan -## Background +## Decision 1: Architecture — SSH Pull (Phase 1) → HTTP Collector (Phase 2) -Evaluating whether to build a custom pi dashboard or switch to Herdr for agent visibility. +**Decision: Phase 1 uses SSH pull. Phase 2 adds HTTP collector on .13.** -## Jump-to-Agent Interaction +Rationale: SSH pull requires zero infrastructure. Every machine already has SSH set up. The Go binary SSHes into each machine and reads state files. Later, the HTTP collector on .13 (alongside OmniRoute) becomes the single source of truth — extensions POST state to it, the viewer reads from it. This gives resilience when machines sleep. -### With tmux (recommended for background agents) +## Decision 2: TUI Tech Stack — Go + Bubble Tea -The dashboard runs this when you press Enter on an agent row: +**Decision: Go binary, Bubble Tea v2 for rendering.** -```bash -tmux attach-session -t pi-work -# You're now in the agent's terminal, stdin/stdout intact -# Answer the prompt, agent continues -# Ctrl+B d → back to dashboard -``` +Rationale: Single portable binary (~10MB), instant startup, no npm/Node dependency. The viewer runs from `~/bin/pi-dashboard` on any machine, including Termux. Bubble Tea is actively maintained (v2.0.8, July 2026). The viewer is simple enough (~400 lines) that Go's learning curve isn't a barrier. -**This works from everywhere** — Zellij pane on .27, terminal on .13, Termux SSH from phone. tmux gives us a universal "jump to" button with no patching. +## Decision 3: Web UI — Phase 2, Optional -The dashboard shows the session name clearly: +**Decision: Not building in Phase 1. Termux SSH → TUI binary is the mobile path.** -``` -║ ● work oc/deepseek-v4 ▓▓▓▓░░ 12:34 48.2K $0.09 ║ -║ 📍 tmux: pi-work ║ -║ └─ Refactor auth middleware ║ -║ [Enter to attach] ║ -``` +Rationale: SSH from Termux renders the TUI perfectly. Web UI is a convenience for glanceable status from a browser — nice but not essential. If built in Phase 2, it's a small Svelte/Vue app served by the dashboard binary itself (`pi-dashboard --web` opens :9877). -### With Zellij (for interactive sessions) +## Decision 4: Task List Integration — Yes, Phase 1 -Zellij has no `zellij --focus-tab --pane` CLI. So for agents running inside Zellij panes, the dashboard shows the location manually: +**Decision: The dashboard shows a task board alongside agent status.** -``` -║ ● explore oc/deepseek-v4 ▓▓░░░░ 03:12 12.1K $0.02 ║ -║ 📍 Zellij: Tab 3 → Pane 2 [switch manually] ║ -``` +Rationale: The sub-agent system already has TaskCreate/TaskUpdate/TaskList/TaskExecute. The extension hooks into these and mirrors task state. The dashboard renders them as a tiered list sorted by status. Sub-agents call `complete_task()` via tool calls. This makes the dashboard a work tracker, not just a status panel. -You can't automate the jump — but you can *see* where to go. +## Decision 5: Polling — 2-second interval, no file watcher -### Recommendation +**Decision: Poll state directory every 2 seconds.** -Run background pi sessions in **tmux** (for jump-to capability) and keep interactive pi sessions in Zellij (readable, not remotely jumpable). The dashboard handles both. +Rationale: Simpler and more robust than fsnotify file watchers (which miss mid-write files, have edge cases on NFS/SSH mounts). A 2-second poll is invisible to the user and uses negligible CPU. + +## Decision 6: Session Naming — `pi-` convention + +**Decision: tmux sessions named `pi-work`, `pi-explore`, `pi-research`, etc.** + +Rationale: The dashboard uses the session name as the connection key. Enter → `tmux attach -t pi-work`. Consistent naming lets the viewer jump without config. + +## Decision 7: Herdr — Try alongside, dashboard is multiplexer-agnostic + +**Decision: The dashboard works with any multiplexer (tmux, Zellij, Herdr, none). No Herdr-specific features in Phase 1.** + +Rationale: The dashboard reads state files and shows connection info. It doesn't care what runs the agent. Herdr can be tried in parallel on WS 2 without affecting the dashboard. --- -## Cross-Machine Visibility +## What Each Component Is -Agents running on your Thinkpad (.51) can be visible on your desktop (.27) dashboard. Three approaches: +### 1. `~/.pi/agent/extensions/dashboard.ts` -### Option A: SSH pull (simplest, recommended) +A pi extension. One file. Runs inside each pi session. -The dashboard viewer has a config: +**What it does:** +- Listens to `agent_start` / `agent_end` / `tool_call` events +- Accumulates: agent type, model, status, duration, token count, last tool call +- Detects blocked state (when `ctx.ui.confirm()` or `ctx.ui.select()` fires and waits) +- Tracks tasks via tool calls (`register_task`, `complete_task`) +- Writes `~/.pi/agent/dashboard/.json` on each event change +- Optionally: POSTs state to HTTP collector on .13 (Phase 2) -```yaml -# ~/.config/pi-dashboard.yaml -local: - path: ~/.pi/agent/dashboard/ +**Not needed:** Any TUI rendering. The extension just collects and writes. -remote: - - host: 192.168.20.51 - user: sam - path: /home/sam/.pi/agent/dashboard/ - - host: 192.168.20.13 - user: sam - path: /home/sam/.pi/agent/dashboard/ -``` +### 2. `~/bin/pi-dashboard` (Go binary) -The viewer SSHes in, reads the files, merges with local state. Shows all machines: +Standalone TUI. One binary. -``` -╔════════════════════════════════════════════════════════════════╗ -║ ⬡ Pi Dashboard (3 machines, 5 agents) Cost: $0.52 ║ -╠════════════════════════════════════════════════════════════════╣ -║ MACHINE AGENT STATUS DURATION TOKENS COST ║ -║ ──────────────────────────────────────────────────────────── ║ -║ .27 work ● running 12:34 48.2K $0.09 ║ -║ .27 explore ● running 03:12 12.1K $0.02 ║ -║ .13 resrch ○ idle 00:47 8.4K $0.00 ║ -║ .51 bugfix ⚠ blocked 01:23 22.1K $0.11 ║ -║ └─ 📍 tmux: pi-bugfix (.51) ║ -╚════════════════════════════════════════════════════════════════╝ -``` +**What it does:** +- Reads all `~/.pi/agent/dashboard/*.json` (local + SSH from remote machines) +- Renders interactive table with agent status, tasks, costs +- Keyboard controls: navigate, attach, filter, quit +- `Enter` → `tmux attach` or shows Zellij tab/pane location +- Polls every 2s for changes -Enter on a remote agent → `ssh -t sam@192.168.20.51 tmux attach-session -t pi-bugfix` → you're in the agent's terminal on the other machine. Detach → back on your desktop. +**Not needed:** HTTP server in Phase 1. -### Option B: HTTP collector (more robust) +### 3. `.pi/agent/mcp.json` entry (optional, Phase 2) -The dashboard extension on each machine pushes state to a central collector (runs on .13 alongside OmniRoute): - -``` -.51 extension ──POST──→ collector (.13:9877) ──→ viewer reads from here -.27 extension ──POST──→ collector (.13:9877) ──→ -.13 extension ──POST──→ collector (.13:9877) ──→ -``` - -The viewer reads from one place. More resilient to transient SSH failures. But needs the collector process to always be running. - -### Option C: Tailscale SSH (if you have it) - -Simplifies auth — SSH keys are already managed. Same as Option A but with shorter hostnames. +If the HTTP collector exists, the viewer can also be an MCP client querying the collector. --- -## Build vs Herdr — Honest Analysis +## Implementation Order -| Criterion | Build the Dashboard | Switch to Herdr | -|-----------|-------------------|----------------| -| **What you keep** | Zellij, all keybindings, layouts, plugins, config.kdl | Nothing. Full rewrite of terminal management | -| **Migration cost** | Zero (it's additive) | High. Every Zellij layout, plugin, keybinding must be recreated in Herdr's system | -| **Agent visibility** | ✅ Unified view of all agents across all machines | ✅ Native per-pane agent state (pane border colors, status icons) | -| **Jump-to-agent** | ✅ One press → tmux attach / shows Zellij location | ✅ Native — same multiplexer | -| **Cross-machine** | ✅ Built for this from day one | ❌ Not designed for it. Would need SSH workarounds | -| **Cost tracking** | ✅ Built in (token count per session) | ❌ No cost data (Herdr doesn't see provider usage) | -| **Phone visibility** | ✅ SSH from Termux → same binary | ✅ Herdr has mobile plugins (AltanS/collie PWA) | -| **Notifications** | ✅ notify-send + any hook | ❌ Socket API exists but alerting isn't built-in | -| **Plugin ecosystem** | ✅ You control the feature set | ✅ 150+ community plugins | -| **Ongoing effort** | Maintenance of ~600 lines of code | Learning Herdr's layout system, keybinding model, plugin API | -| **Risk** | Low — additive, revert by deleting the binary | Medium — need to verify Herdr works with pi's extension system, sub-agents, OmniRoute | -| **Lock-in** | None — standard Go/Node TS | Moderate — Herdr uses its own layout YAML, plugin format | +### Step 1: dashboard.ts extension -### The real question +- [x] Correctly identify that the state file avoids reading the existing subagent code +- [ ] Write the extension in `~/.pi/agent/extensions/dashboard.ts` +- [ ] Add event handlers: `agent_start`, `agent_end`, `tool_call` +- [ ] Add blocked detection (intercept `ctx.ui.select/confirm/input`) +- [ ] Add task tracking via tool registration +- [ ] Write state to `~/.pi/agent/dashboard/.json` atomically +- [ ] Test: launch a pi session, verify state file updates +- [ ] Commit to Gitea -Herdr solves a different problem. It's a **multiplexer** that happens to have agent awareness. You're asking whether to replace Zellij with a multiplexer that has the feature you want built in, versus adding the feature to your existing setup. +### Step 2: Go TUI viewer -If you were starting from scratch today, Herdr would be a strong choice. But you have: +- [ ] Initialize Go module at `~/src/pi-dashboard/` +- [ ] Add Bubble Tea dependency +- [ ] Implement state file reader (local + SSH) +- [ ] Render agent table with colors and status indicators +- [ ] Add keyboard controls (nav, attach, filter, quit) +- [ ] Add polling loop (2s interval) +- [ ] Build binary to `~/bin/pi-dashboard` +- [ ] Test: launch 2-3 background pi sessions, verify dashboard shows them -- A polished Zellij config at `/etc/nixos/home/sam/config/zellij/config.kdl` -- falcode-zellij already wired in -- Years of muscle memory -- neovim running inside Zellij with custom layouts +### Step 3: Cross-machine (SSH pull) -**The dashboard gives you agent visibility without touching any of that.** Herdr would require rebuilding all of it. +- [ ] Add `~/.config/pi-dashboard.yaml` config file support +- [ ] Implement SSH state reader with timeout and error handling +- [ ] Test: verify agents on .51 and .13 appear in .27's dashboard +- [ ] Test: `Enter` on remote agent → SSH + tmux attach -### When Herdr makes sense +### Step 4: Task list view -If you hit these limits with the dashboard approach: -- "I want to see agent state without a separate tool" → Herdr's pane indicators are more integrated -- "I want Herdr's plugin ecosystem" → The diff viewer, file tree, focus plugins are genuinely useful -- "Zellij's WASM plugin system is too limiting" → Herdr's Rust plugin system is also WASM but with more hooks +- [ ] Add task board panel (toggle with Tab) +- [ ] Show tasks grouped by status (pending / in_progress / done) +- [ ] Show which agent is assigned to which task +- [ ] Integrate with existing TaskCreate/TaskUpdate APIs in pi -But these are "nice to have" problems, not "blocking" problems. +### Step 5: Try Herdr + +- [ ] `nix shell nixpkgs#herdr` or download binary +- [ ] Create a simple Herdr layout for WS 2 +- [ ] Run a pi session inside Herdr +- [ ] Verify dashboard picks it up from state files +- [ ] Evaluate: is the pain of migration worth Herdr's native visibility? + +### Step 6: HTTP collector + web UI (Phase 2, optional) + +- [ ] Add POST endpoint to dashboard.ts extension +- [ ] Write collector server (Go, small binary on .13) +- [ ] Update viewer to prefer collector over SSH +- [ ] If web UI wanted: Svelte frontend served by collector --- -## Effort Estimate (with AI assistance) +## Files to Create -| Component | Raw AI generation | Debugging + testing | Total | -|-----------|------------------|-------------------|-------| -| `dashboard.ts` extension | 30 minutes | 1 hour (integration testing) | 1.5h | -| Go TUI viewer | 1 hour | 2 hours (edge cases, resize, watcher races) | 3h | -| Cross-machine SSH | 30 minutes | 1 hour (error handling, timeouts, auth) | 1.5h | -| Integration + polish | 30 minutes | 1.5 hours (naming conventions, config file, escape sequences) | 2h | -| **Total** | **2.5h** | **5.5h** | **~8h** | - -**No, it's not 1-2 hours.** That might get you a proof-of-concept that shows text on screen. Production-ready means: - -- File watcher doesn't crash when a state file is mid-write -- Terminal resize doesn't corrupt the display -- SSH to remote machines doesn't hang if they're offline -- Pressing Enter on a remote agent actually starts the SSH session and attaches -- The extension handles edge cases (agent crash, session kill, machine sleep) -- The dashboard recovers when the extension restarts and writes fresh state - -Each of these is a development loop: guess → test → fix. AI can generate the first pass fast, but debugging real-time cross-process systems is inherently iterative. - -**The optimistic floor is one focused afternoon.** 3-4 hours if you've had coffee and the stars align. 8-12 hours spread over a few days is the honest expectation. +| File | Location | Purpose | +|------|----------|---------| +| `dashboard.ts` | `~/.pi/agent/extensions/` | Pi extension: collects state, writes files, tracks tasks | +| `pi-dashboard/` | `~/src/pi-dashboard/` | Go module for the TUI viewer | +| `pi-dashboard/main.go` | entry point | Bubble Tea model, view, update | +| `pi-dashboard/config.go` | config | YAML config reader for local paths + SSH remotes | +| `pi-dashboard/state.go` | state reader | Reads JSON files, polls, SSH fetch | +| `pi-dashboard/tui.go` | TUI rendering | Table layout, colors, keybindings | +| `pi-dashboard/go.mod` | module | Dependencies | +| `~/.config/pi-dashboard.yaml` | user config | Machine list, paths, polling interval | +| `~/bin/pi-dashboard` | binary | Built Go binary | --- -## Summary +## What You Don't Need -| Question | Answer | -|----------|--------| -| Jump to agent terminal? | ✅ tmux: one keypress. Zellij: shows location. | -| Cross-machine visibility? | ✅ SSH pull or HTTP collector. Viewer shows all machines. | -| Build vs Herdr? | **Build.** Herdr replaces Zellij (costly migration). Dashboard is additive (no migration). If you were starting fresh, Herdr would win. | -| Realistic effort? | **~8 hours** with AI, not 1-2. Integration testing is the bottleneck, not code generation. | +- A database (state files are JSON, small, temporary) +- A daemon process (the viewer is stateless, polls files) +- Node.js on the viewer machine (Go binary is self-contained) +- Web framework (Phase 1 is TUI-only) +- Herdr, Orca, Buzz integration (dashboard is agnostic) + +--- + +## Open Question for You + +The task list integration: do you want the task board to be a separate screen (Tab to toggle between agent view and task board), or inline within the agent table (tasks shown under each agent row)?