Monitor your Pi / OMP sessions

A web-based dashboard for monitoring and interacting with pi agent sessions from any browser, including mobile.

Website: blackbelttechnology.github.io/pi-agent-dashboard — animated tour, screenshots, and install guide.

Changelog: see CHANGELOG.md for release notes.

Releasing: see docs/release-process.md for the cut-a-release workflow.

Real-time session mirroring— See all active pi sessions with live streaming messagesBidirectional interaction— Send prompts and commands from the browserWorkspace management— Organize sessions by project folder with pinned directories and drag-to-reorderCommand autocomplete—/ prefix triggers command dropdown with filteringSession statistics— Token counts, costs, model info, thinking level, context usage barElapsed time tracking— Live ticking counters on running operations, final duration on completed tool calls and reasoning blocksMobile-friendly— Responsive layout with swipe drawer, touch targets, and mobile action menusSession spawning— Launch new pi sessions from the dashboard (headless by default, or via tmux)PromptBus architecture— Unified prompt routing with adapters (TUI, dashboard, custom). Interactive dialogs (confirm/select/input/editor/multiselect) survive page refresh and server restart. First-response-wins semantics with cross-adapter dismissal.On-demand session loading— Browse historical sessions with lazy-loaded content from pi session filesIntegrated terminal— Full browser-based terminal emulator (xterm.js + node-pty) with ANSI color support, scrollback, and keep-alivepi-flows integration— Live flow execution dashboard with agent cards, detail views, flow graph visualization, summary, abort/auto controls. Launch flows and design new ones with the Flow Architect — all from the browser. Fork decisions and subagent dialogs forwarded via PromptBus.Force kill escalation— Two-click Stop button (in command bar and on running tool cards): first click sends soft abort, second click force-kills the process (SIGTERM → SIGKILL). 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 commandsBrowser-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 sidebarDiff viewer— Side-by-side and unified diff views with file tree navigation for reviewing agent changesEditor integration— Open files in your preferred editor (VS Code, Cursor, etc.) directly from tool call cardsMarkdown preview— Rendered markdown views with search, mermaid diagrams, and syntax highlightingNetwork discovery— mDNS-based auto-discovery of other dashboard servers on the local network; connect to known remote servers

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

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.

There are three ways to use the dashboard, from simplest to most flexible:

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.

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.

git clone https://github.com/BlackBeltTechnology/pi-agent-dashboard.git
cd pi-agent-dashboard
npm install
pi install /path/to/pi-agent-dashboard

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 | [email protected]: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 | [email protected]: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).