obsidian-vault/100 inbox/Pi Dashboard.md

Pi Dashboard — Build Plan & Checklist

Task Checklist

• Step 1: dashboard.ts extension — written, tested, deployed to .13 (.51 offline)
  • Event hooks: agent_start, agent_end, tool_call
  • Write agent state JSON files atomically (~/.pi/agent/dashboard/<session>.json)
  • Task tools: register_task, complete_task, list_tasks (todo.txt format)
  • NTFY + Apprise notifications on completion
  • Session name detection (tmux aware, configurable via PI_SESSION env)
  • Tested: state files written correctly, no crashes
• Step 2: Install companion tools — Tuxedo (built from source via nix), Hunk (already available)
  • Tuxedo: /home/sam/bin/tuxedo (NixOS-compatible nix build)
  • Hunk: available via nix profile at /etc/profiles/per-user/sam/bin/hunk
• Step 3: Go TUI viewer — built and deployed to .27 and .13
  • Initialize Go module at ~/src/pi-dashboard/ (Go 1.26)
  • Local state file reader + TUI table rendering (Bubble Tea + Bubbles table)
  • Keyboard controls: Enter (attach), d (Hunk), Tab (Tuxedo), r (refresh), q (quit)
  • 2s polling loop
  • Built to ~/bin/pi-dashboard (5.4MB static binary)
  • Deployed to .13 via scp
  • --list mode for non-TTY testing, --help for usage
• Step 4: Cross-machine SSH pull
  • YAML config file at ~/.config/pi-dashboard.yaml (remotes: .13, .51)
  • SSH remote state reader (shells out to ssh user@host cat .../*.json)
  • Remote attach (local: tmux attach, remote: ssh -t user@host tmux attach)
  • Viewer deployed to .13
• Step 5: Try Herdr
  • Install Herdr via nix
  • Create test layout on WS 2
  • Run pi inside Herdr, verify dashboard picks it up
  • Evaluate migration vs keeping Zellij

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  pi sessions (each machine)                                     │
│                                                                 │
│  pi (with dashboard.ts extension)                               │
│  ├── agent_start → track: status, model, duration, tokens       │
│  ├── agent_end   → notify: NTFY/Apprise + mark complete         │
│  ├── tool_call   → track: last tool, tokens consumed            │
│  └── register_task / complete_task → write to todo.txt          │
│       │                                                         │
│       └── Writes to:                                            │
│           ~/.pi/agent/dashboard/<session>.json    (agent state) │
│           ~/.pi/agent/dashboard/tasks/todo.txt   (task list)    │
│                                                                 │
│  On agent_end / error:                                          │
│  └── curl → NTFY server (phone notification)                    │
│  └── apprise → Slack/Telegram/email (configured routes)         │
└─────────────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│  pi-dashboard viewer (Go + Bubble Tea)                          │
│                                                                 │
│  Reads: ~/.pi/agent/dashboard/*.json (local + SSH remote)       │
│  Renders: agent status table with cost, duration, location      │
│  Controls:                                                      │
│    Enter → tmux attach -t <session> (jump to agent)             │
│    d     → hunk diff (review agent's worktree changes)          │
│    Tab   → launch Tuxedo (task list in todo.txt)                │
│    r     → force refresh                                        │
│    q     → quit                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Decisions

Decision	Choice	Why
State transfer	SSH pull Phase 1 → HTTP collector on .13 Phase 2	Zero infra to start, resilient later
TUI framework	Go + Bubble Tea	Single binary, fast, portable
Web UI	Phase 2, optional	SSH from Termux works for Phase 1
Task board	Use Tuxedo — don't build custom	Already polished with vim keys, phone capture
Diff review	Use Hunk — don't build custom	Purpose-built for agent changeset review
Notifications	Use NTFY + Apprise — don't build custom	Both already available, extension calls curl/apprise
Polling	2s intervals, no file watcher	Simple, no edge cases
Session naming	pi- (pi-work, pi-explore)	Consistent jump target
Herdr	Try alongside, no special integration	Dashboard is multiplexer-agnostic