Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

debug-dashboard

Diagnose problems in the running pi-agent-dashboard system: server.log, /api/health, bridge WebSocket connectivity, vitest triage, known-issue FAQ entries. Routes UI/visual issues to the browser skill. Use when the server seems hung, a pi session won''t connect, tests fail mysteriously, the dashboard shows a blank page, restart loops, port conflicts, or any "why isn''t X working" question.

BlackBeltTechnology · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add BlackBeltTechnology/pi-agent-dashboard --skill debug-dashboard

About this skill


name: debug-dashboard description: 'Diagnose problems in the running pi-agent-dashboard system: server.log, /api/health, bridge WebSocket connectivity, vitest triage, known-issue FAQ entries. Routes UI/visual issues to the browser skill. Use when the server seems hung, a pi session won''t connect, tests fail mysteriously, the dashboard shows a blank page, restart loops, port conflicts, or any "why isn''t X working" question.'

Debug Dashboard

System-level debugging for the running pi-agent-dashboard. Three layers:

   ┌─────────────────────────────────────────────────────────┐
   │  Layer 1 — Is the server alive?                         │
   │            npx tsx ./scripts/health-probe.ts            │
   │            npx tsx ./scripts/tail-server-log.ts         │
   └─────────────────────────────────────────────────────────┘
                            │
                            ▼
   ┌─────────────────────────────────────────────────────────┐
   │  Layer 2 — Are the bridges connecting?                  │
   │            npx tsx ./scripts/list-sessions.ts           │
   │            npx tsx ./scripts/tail-server-log.ts --errors│
   └─────────────────────────────────────────────────────────┘
                            │
                            ▼
   ┌─────────────────────────────────────────────────────────┐
   │  Layer 3 — Is the UI rendering?                         │
   │            (use the browser skill)                     │
   └─────────────────────────────────────────────────────────┘

First moves — always run these

npx tsx ./scripts/health-probe.ts        # mode + uptime + version, or "not-running"
npx tsx ./scripts/tail-server-log.ts     # last 50 lines of current run
npx tsx ./scripts/list-sessions.ts       # connected pi sessions via REST

Scripts are TypeScript (cross-platform). All invocations use npx tsx so they work on Linux, macOS, and Windows. tsx is already a project dep.

If health-probe says "not-running" → server isn't up. Check server.log for the most recent start banner ([bootstrap] ready ...) and what came after. The log appends with timestamped headers per start, so the last banner block is the relevant one.

When the server is up but misbehaving

SymptomLikely causeWhere to look
Restart loopsStale port held by zombie, or restart racing with bridge auto-startlsof -i :8000, then pi-dashboard stop (kills by port, not just PID)
EADDRINUSE on startConcurrent spawn from multiple pi sessionsHarmless — losing process exits silently. Check log.
Bridge connects then disconnectsserver_restarting broadcast active, or version skewgrep server_restarting in server.log; check /api/health for version
Blank page in browserVite not running in dev mode (silent fallback to prod build); or auth blockingCheck /api/health.mode; check auth settings
New session won't start / yellow spawn_register_timeout, no cardpi crashed at startup (bad extension) OR host overloadSee references/known-issues.md → "New session won't start" — manual pi --mode rpc run splits crash vs overload
Cannot connect to dashboard server on Electron bootlaunchDashboardServer fell back to process.execPath (Electron GUI binary)See references/known-issues.md → "Electron Node bin selection"
Fastify crashes immediatelyBad Node version (22.0–22.17.x or 24.1–24.2.x per nodejs/node#58515)node --version — must be ≥ 22.18.0

Full known-issue catalogue: references/known-issues.md.

When tests fail mysteriously

Use the tee→grep pattern. Never rerun to inspect — capture once, grep forever:

npx tsx ./scripts/run-tests-triage.ts                 # all tests, tee to OS tmpdir, summarize failures
npx tsx ./scripts/run-tests-triage.ts packages/server # restrict to one package's vitest
npx tsx ./scripts/run-tests-triage.ts -t 'my test'    # by test name

After it finishes, the log lives at:

  • Linux/macOS: /tmp/pi-test.log
  • Windows: %TEMP%\pi-test.log

You can re-grep / re-read with custom patterns; the script prints the absolute path on each run.

Patterns + per-package vitest configs + watch mode are documented in references/test-failure-triage.md.

When the UI is the problem

This skill stops at "the server says X but the UI shows Y". For visual debugging — verifying layouts, screenshotting, hunting console errors, testing responsive breakpoints — switch to the browser skill (shipped by the dashboard bridge extension to every session). Quick pointer: see references/ui-debug.md.

When you must verify a change without touching the live server

The live :8000 server runs MAIN-repo code — /api/restart never loads worktree edits, and a careless npm run build leaks into packages/client/dist (what live serves). To verify a UI/worktree change or serve a review mockup in full isolation (temp HOME, non-8000 ports, PI_DASHBOARD_NO_MDNS=1), see references/isolated-verification.md.

Log file locations

All log + config files. Worth bookmarking. See references/log-locations.md for the full map.

PathContents
~/.pi/dashboard/server.logDaemon stdout/stderr, append mode, timestamped headers per start
~/.pi/dashboard/server.pidPID file (may be stale; use lsof -i :8000 to confirm)
~/.pi/dashboard/config.jsonLive config (port, piPort, auth, tunnel, plugins)
~/.pi/dashboard/zrok.pidTunnel PID file
~/.pi/dashboard/model-proxy.jsonlModel proxy request log (50 MB rotation)
~/.pi/dashboard/tool-overrides.jsonTool registry overrides
/tmp/pi-test.logLast test run (when you used the tee→grep pattern)
~/.pi/agent/sessions/Per-sess
Read the complete source ↗