pi-agent-dashboard

PI Dashboard

One browser tab to command an army of pi agents. Spawn parallel sessions, watch reasoning live, attach OpenSpec changes, ship work — from your laptop or phone.

🌐 Website & demo: blackbelttechnology.github.io/pi-agent-dashboard — animated tour, screenshots, and install guide. 💬 Community: Join our Discord — questions, help, and release news. 📝 Changelog: CHANGELOG.md

Note: This dashboard only works with pi. Oh My Pi is not supported.

---

Screenshots

---

Table of contents

• Quickstart
• Features
• Chinese UI
• Prerequisites
• Configuration
• Usage
• Recommended extensions
• Authoring a dashboard plugin
• Troubleshooting
• Architecture
• Monitoring
• Development
• Building the Electron app
• CI/CD & releasing
• License

---

Quickstart

Three install paths, pick one:

A — Electron desktop app (no prerequisites)

Download a pre-built installer from GitHub Releases:

Platform	Download
macOS (Apple Silicon / Intel)	.dmg (arm64 / x64)
Linux (x64 / ARM64)	.deb or .AppImage
Windows (x64 / ARM64)	.zip

macOS requirement: macOS 13 (Ventura) or newer — Intel and Apple Silicon both supported. macOS 12 (Monterey) and older are not supported (Electron 44 dropped macOS 12); users on those versions keep their currently installed version and are not offered the newer update.

On first launch a setup wizard walks you through mode selection (standalone vs. power-user), API key / OAuth sign-in, and recommended extensions. The standalone mode bundles Node.js and auto-installs pi + dashboard + openspec into ~/.pi-dashboard/ — no terminal, npm, or Node.js required.

Picking the right macOS DMG: run uname -m in Terminal — arm64 means Apple Silicon (M1/M2/M3/M4), x86_64 means Intel. Or open  Apple menu → About This Mac and read the chip name. Download the matching DMG; if you grab the wrong one macOS will refuse to launch the app with a "cannot be opened" error.

First-run unblocking (unsigned binaries):

• macOS — the DMGs are not yet notarized. Either right-click PI-Dashboard.app → Open the first time, or clear all extended attributes from Terminal:

  xattr -cr /Applications/PI-Dashboard.app
  

  Use -cr (clear, recursive) rather than -d com.apple.quarantine — it's idempotent and won't print No such xattr: com.apple.quarantine when the attribute isn't there. That message is harmless; it just means quarantine was never set or already cleared.
• Windows — SmartScreen warns on first launch. Click More info → Run anyway, or right-click the downloaded .exe / .zip → Properties → tick Unblock → OK before running. For ZIPs, unblock the archive before extracting.

Note: A future release will rename the macOS DMGs to PI-Dashboard-darwin-arm64-<ver>.dmg and PI-Dashboard-darwin-x64-<ver>.dmg (previously a single PI Dashboard.dmg was produced and silently overwrote one arch on each release). Direct download links pointing at the unsuffixed filename will 404 from that release onward; please link to the Releases page instead. See OpenSpec change fix-darwin-dmg-arch-collision.

B — pi package (recommended for CLI users)

If you don't have pi yet, you can install the dashboard directly via npm — pi/openspec/tsx ship as regular npm dependencies, so a single install brings everything in:

npm install -g @blackbelt-technology/pi-agent-dashboard
pi-dashboard
# open http://localhost:8000

If pi is already installed, the bridge-extension flow is equivalent:

pi install npm:@blackbelt-technology/pi-agent-dashboard
pi

The bridge extension auto-starts the dashboard server on first launch:

🌐 Dashboard started at http://localhost:8000

Open http://localhost:8000 in any browser. All active pi sessions appear automatically. See Prerequisites for Node.js / build-tool requirements.

Windows install (PowerShell, Administrator)

Windows has a few extra one-time setup steps. Run the following in an Administrator PowerShell session:

# 1. Enable long paths (required — npm node_modules nesting exceeds 260 chars)
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f

# 2. Install Node.js LTS 22 via winget (ships >= 22.19 so no node-guard refusal)
winget install -e --id OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements

# 3. CLOSE this PowerShell, open a NEW one as Administrator (PATH refresh)

# 4. Verify
node --version    # expect v22.19+ (any 22.x >= 22.19, NOT v22.0–v22.18)
npm --version     # expect 10.x

# 5. Install
npm install -g @blackbelt-technology/pi-agent-dashboard

# 6. Start (foreground first time so you can see any errors)
pi-dashboard start

# 7. From the browser
start http://localhost:8000

C++ build tools are typically not required — node-pty ships a Windows x64 prebuild. Install Visual Studio Build Tools only if the prebuild fails to load. See docs/installation-windows.md for more detail (offline / tarball / nvm-windows caveats).

C — From source (contributors)

Before your first change, read CONTRIBUTING.md — features and bugfixes go through a spec-first pipeline (explore → plan → build → ship), not a plain branch-and-PR flow.

git clone https://github.com/BlackBeltTechnology/pi-agent-dashboard.git
cd pi-agent-dashboard
corepack enable                            # activates the pinned pnpm (packageManager field)
pnpm install
pnpm run build                             # one-time client build
pi install /path/to/pi-agent-dashboard     # global
# or: pi install -l /path/to/pi-agent-dashboard   # project-local only

Use the local checkout as the global pi-dashboard command

By default, pi-dashboard on your PATH refers to whatever copy was installed globally (via npm i -g or the Electron bundle). To make it point at your working tree instead — so every edit is live and bridge auto-start uses your changes — link the workspace:

pnpm run link:local     # symlinks `pi-dashboard` on PATH to packages/server/bin/pi-dashboard.mjs
pi-dashboard status
pnpm run unlink:local   # restore (removes the global symlink)

The link survives across shells. Every invocation — including pi's bridge auto-spawn — runs packages/server/src/cli.ts via jiti, so you don't need to rebuild the server on edits. The client still requires pnpm run build (or pnpm run dev for HMR).

Windows note: symlink creation needs an admin shell or Windows Developer Mode enabled. Everything else works the same as POSIX.

To try the extension in a single pi session without registering it:

pi -e /path/to/pi-agent-dashboard/packages/extension/src/bridge.ts

Remove with pi remove /path/to/pi-agent-dashboard. Alternatively, add the package path directly to ~/.pi/agent/settings.json (global) or .pi/settings.json (project) under "packages": [...].

D — Docker (self-contained, no host install)

Run the whole ecosystem — server, pi agent, code-server, zrok, tmux, terminals — in one container. No host install of pi, Node, or any tool.

cd docker
cp .env.example .env          # add ANTHROPIC_API_KEY (optional)
docker compose up -d --build
# open http://localhost:8000

State persists in a named volume; API keys seed into auth.json on first run (or add providers later via the UI). Mount host projects at their identical absolute paths with PI_WORKSPACES="/abs/a:/abs/b" ./up.sh (auto-pinned on first run). The Electron desktop app can attach to a Docker-hosted server via the wizard's Remote mode — no local install. Full guide, volume performance profiles, dev mode, and external-gateway config: docker/README.md. For a disposable, fully isolated instance for manual browser QA (can't collide with a running host dashboard): docker/TESTING.md.

E — Claude Code / Claude Desktop plugin

Start the local dashboard on demand and drive pi sessions from Claude Code. Global install only with explicit consent. See packages/claude-plugin/README.md.

---

Features

Sessions & chat

• Real-time session mirroring — all active pi sessions with live streaming messages
• Bidirectional interaction — send prompts and commands from the browser
• Session statistics — token counts, costs, model info, thinking level, context usage bar
• Elapsed time tracking — live ticking counters on running operations, final duration on completed tool calls and reasoning blocks
• Session spawning — launch new pi sessions from the dashboard (headless by default, or via tmux)
• On-demand session loading — browse historical sessions with lazy-loaded content from pi session files
• Force kill escalation — two-click Stop button; first click sends soft abort, second force-kills (SIGTERM → SIGKILL). Session preserved as "ended" for resume/fork.

Workspace & UI

• Workspace management — organize sessions by project folder with pinned directories and drag-to-reorder
• Command autocomplete — / prefix triggers a filtering dropdown
• Mobile-friendly — responsive layout with swipe drawer, touch targets, and mobile action menus
• Markdown preview — rendered markdown views with search, mermaid diagrams, syntax highlighting, and safe handling for raw HTML ref attributes