# Pi Dashboard — Architecture Decision Record

## Background

Evaluating whether to build a custom pi dashboard or switch to Herdr for agent visibility.

## Jump-to-Agent Interaction

### With tmux (recommended for background agents)

The dashboard runs this when you press Enter on an agent row:

```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
```

**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.

The dashboard shows the session name clearly:

```
║  ● work     oc/deepseek-v4     ▓▓▓▓░░ 12:34    48.2K   $0.09  ║
║   📍 tmux: pi-work                                              ║
║   └─ Refactor auth middleware                                   ║
║     [Enter to attach]                                           ║
```

### With Zellij (for interactive sessions)

Zellij has no `zellij --focus-tab --pane` CLI. So for agents running inside Zellij panes, the dashboard shows the location manually:

```
║  ● explore  oc/deepseek-v4     ▓▓░░░░ 03:12    12.1K   $0.02  ║
║   📍 Zellij: Tab 3 → Pane 2    [switch manually]               ║
```

You can't automate the jump — but you can *see* where to go.

### Recommendation

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.

---

## Cross-Machine Visibility

Agents running on your Thinkpad (.51) can be visible on your desktop (.27) dashboard. Three approaches:

### Option A: SSH pull (simplest, recommended)

The dashboard viewer has a config:

```yaml
# ~/.config/pi-dashboard.yaml
local:
  path: ~/.pi/agent/dashboard/

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/
```

The viewer SSHes in, reads the files, merges with local state. Shows all machines:

```
╔════════════════════════════════════════════════════════════════╗
║  ⬡ 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)              ║
╚════════════════════════════════════════════════════════════════╝
```

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.

### Option B: HTTP collector (more robust)

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.

---

## Build vs Herdr — Honest Analysis

| 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 |

### The real question

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.

If you were starting from scratch today, Herdr would be a strong choice. But you have:

- 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

**The dashboard gives you agent visibility without touching any of that.** Herdr would require rebuilding all of it.

### When Herdr makes sense

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

But these are "nice to have" problems, not "blocking" problems.

---

## Effort Estimate (with AI assistance)

| 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.

---

## Summary

| 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. |