GitHub - BlackBeltTechnology/pi-agent-dashboard

Session preserved as "ended" for resume/fork. Repeated tool calls (e.g. health check loops) are auto-collapsed with a count badge. Searchable select dialogs — Keyboard-navigable picker with real-time filtering for OpenSpec changes and flow commands Browser-based provider auth — Sign in to Anthropic, OpenAI Codex, GitHub Copilot, Gemini CLI, and Antigravity directly from Settings. Enter API keys for other providers. Credentials saved to ~/.pi/agent/auth.json and live-synced to running sessions. Package management — Browse, install, update, and remove pi packages from the dashboard. Search the npm registry for pi-package extensions/skills/themes, install from npm or git URL, manage global packages in Settings and local packages per workspace. All active sessions auto-reload after changes. OpenSpec integration — Browse specs, view archive history, manage changes, and create new changes from the session sidebar Diff viewer — Side-by-side and unified diff views with file tree navigation for reviewing agent changes Editor integration — Open files in your preferred editor (VS Code, Cursor, etc.) directly from tool call cards Markdown preview — Rendered markdown views with search, mermaid diagrams, and syntax highlighting Network discovery — mDNS-based auto-discovery of other dashboard servers on the local network; connect to known remote servers

Architecture

graph LR subgraph "Per pi session" B[Bridge Extension] end

subgraph "Dashboard Server (Node.js)" PG[Pi Gateway :9999] BG[Browser Gateway :8000] HTTP[HTTP / Static Files] MEM[(In-Memory Store)] JSON[(JSON Files)] end

subgraph "Browser" UI[React Web Client] end

B <-->|WebSocket| PG UI <-->|WebSocket| BG UI -->|HTTP| HTTP PG --- MEM PG --- JSON BG --- MEM

Loading

The system has three components:

Component Location Role

Bridge Extension packages/extension/ Runs in every pi session. Forwards events, relays commands, auto-starts server, hosts PromptBus.

Dashboard Server packages/server/ Aggregates events in-memory, persists metadata to JSON, serves the web client, manages terminals.

Web Client packages/client/ React + Tailwind UI with real-time WebSocket updates.

Shared packages/shared/ TypeScript types, protocols, and utilities shared across all packages.

See docs/architecture.md for detailed data flows, reconnection logic, and persistence model. Getting Started There are three ways to use the dashboard, from simplest to most flexible: Option A: Electron Desktop App (standalone — no prerequisites) Download a pre-built installer from GitHub Releases for your platform:

Platform Download

macOS (Apple Silicon) .dmg (arm64)

macOS (Intel) .dmg (x64)

Linux (x64) .deb or .AppImage

Linux (ARM64) .deb

Windows (x64) .exe (NSIS installer), .zip, or portable .exe

Windows (ARM64) .zip or portable .exe

On first launch, a setup wizard guides you through:

Choose a mode:

Standalone — Bundles Node.js and auto-installs pi + dashboard + openspec into ~/.pi-dashboard/. No Node.js, npm, or build tools needed. Power User — Uses your existing system-installed pi and dashboard.

Configure an API key — Enter your Anthropic/OpenAI key or sign in via browser-based OAuth. Recommended extensions — Install the curated set of pi extensions the dashboard is built to work with (see Recommended extensions below). You can skip and manage them later from the Packages tab. Done — The app discovers or spawns a dashboard server automatically.

No terminal, no npm, no Node.js required. The Electron app is fully self-contained in standalone mode. It bundles a Node.js runtime, spawns the dashboard server internally, and manages all dependencies. System tray integration keeps it running in the background.

Option B: pi Package (recommended for CLI users) Requires pi (or Oh My Pi) and Node.js ≥ 22.18.0 (or ≥ 24.3.0). Older Node 22.x / 24.x builds are affected by nodejs/node#58515 which crashes Fastify at startup. pi install npm:@blackbelt-technology/pi-dashboard pi The bridge extension auto-starts the dashboard server on first launch.

You'll see: 🌐 Dashboard started at http://localhost:8000

Open http://localhost:8000 in any browser. All active pi sessions appear automatically. Option C: Local development install git clone https://github.com/BlackBeltTechnology/pi-agent-dashboard.git cd pi-agent-dashboard npm install pi install /path/to/pi-agent-dashboard Recommended extensions The dashboard integrates tightly with a small, curated set of pi extensions — for custom tool rendering, the Flow dashboard, and anthropic-messages protocol compatibility. The wizard's Recommended-extensions step installs them in one go; the Packages tab and a top-of-page banner keep them discoverable afterwards.

Extension Source Status Unlocks

pi-anthropic-messages git@github.com:BlackBeltTechnology/pi-anthropic-messages.git required Tool calls on Claude-model Anthropic OAuth / 9Router cc/* / pi-model-proxy providers. Without it, tool calls fall back to Claude Code's built-in bash_ide sandbox and fail.

@tintinweb/pi-subagents npm:@tintinweb/pi-subagents strongly suggested Agent tool card UI, subagent activity badge, get_subagent_result / steer_subagent renderers.

pi-flows git@github.com:BlackBeltTechnology/pi-flows.git strongly suggested Flow dashboard, role aliases (@planning, @coding, …), subagent / flow_write / flow_results / agent_write / ask_user / skill_read / finish tools.

pi-web-access npm:pi-web-access strongly suggested web_search, code_search, fetch_content, get_search_content.

pi-agent-browser npm:pi-agent-browser optional browser tool (open, snapshot, click, screenshot).

Authoritative source of truth: packages/shared/src/recommended-extensions.ts. Descriptions, versions, and installed-state are enriched live at runtime via GET /api/packages/recommended (falling back to offline descriptions on network failure). GitHub SSH notes The pi-flows and pi-anthropic-messages entries install via pi install git@github.com:… (SSH).

If your system doesn't have a GitHub SSH key configured the clone will fail with a "Permission denied (publickey)" error. Set up a key by following GitHub's SSH docs, or substitute the equivalent HTTPS URL in the manifest if your fork is public. Quick test (without installing) To try the extension in a single pi session without registering it: pi -e /path/to/pi-agent-dashboard/packages/extension/src/bridge.ts Prerequisites Only needed for Option B/C (the Electron app handles everything automatically).

Requirement Why Install

pi or Oh My Pi The AI coding agent that the dashboard monitors npm i -g @mariozechner/pi-coding-agent

Node.js ≥ 22.18.0 Runtime for the dashboard server (older 22.x / 24.x affected by nodejs/node#58515) nodejs.org

C++ build tools Required by node-pty native addon for terminal emulation Xcode CLI Tools (macOS) / build-essential (Linux)

Optional tools

Tool Purpose When needed

tmux Spawn new pi sessions from the browser in a tmux window When spawnStrategy is "tmux"

zrok Expose dashboard over the internet via tunnel (auto-connects on server start). Install with brew install zrok (macOS) and run zrok enable <token> to enroll — the dashboard reads zrok's own config (~/.zrok2/environment.json), no keys are stored in the dashboard. Uses reserved shares for persistent URLs across restarts. When tunnel.enabled is true (default)

Configuration Config file: ~/.pi/dashboard/config.json (auto-created with defaults on first run) Tool path overrides (optional, machine-local): ~/.pi/dashboard/tool-overrides.json — see Tool resolution & overrides below. { "port": 8000, "piPort": 9999, "autoStart": true, "autoShutdown": false, "shutdownIdleSeconds": 300, "spawnStrategy": "headless", "tunnel": { "enabled": true, "reservedToken": "auto-created-on-first-run" }, "devBuildOnReload": false,