8.7 KiB
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:
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:
# ~/.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. |