# Pi Dashboard — Build Plan & Checklist

## Task Checklist

- [x] **Step 1: dashboard.ts extension** — written, tested, deployed to .13 (.51 offline)
  - [x] Event hooks: agent_start, agent_end, tool_call
  - [x] Write agent state JSON files atomically (`~/.pi/agent/dashboard/<session>.json`)
  - [x] Task tools: register_task, complete_task, list_tasks (todo.txt format)
  - [x] NTFY + Apprise notifications on completion
  - [x] Session name detection (tmux aware, configurable via PI_SESSION env)
  - [x] Tested: state files written correctly, no crashes
- [x] **Step 2: Install companion tools** — Tuxedo (built from source via nix), Hunk (already available)
  - [x] Tuxedo: `/home/sam/bin/tuxedo` (NixOS-compatible nix build)
  - [x] Hunk: available via nix profile at `/etc/profiles/per-user/sam/bin/hunk`
- [x] **Step 3: Go TUI viewer** — built and deployed to .27 and .13
  - [x] Initialize Go module at ~/src/pi-dashboard/ (Go 1.26)
  - [x] Local state file reader + TUI table rendering (Bubble Tea + Bubbles table)
  - [x] Keyboard controls: Enter (attach), d (Hunk), Tab (Tuxedo), r (refresh), q (quit)
  - [x] 2s polling loop
  - [x] Built to ~/bin/pi-dashboard (5.4MB static binary)
  - [x] Deployed to .13 via scp
  - [x] `--list` mode for non-TTY testing, `--help` for usage
- [x] **Step 4: Cross-machine SSH pull**
  - [x] YAML config file at ~/.config/pi-dashboard.yaml (remotes: .13, .51)
  - [x] SSH remote state reader (shells out to `ssh user@host cat .../*.json`)
  - [x] Remote attach (local: `tmux attach`, remote: `ssh -t user@host tmux attach`)
  - [x] 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-<role> (pi-work, pi-explore) | Consistent jump target |
| Herdr | Try alongside, no special integration | Dashboard is multiplexer-agnostic |