Debug Dashboard
Diagnose problems in the running pi-agent-dashboard system. Tail /.pi/dashboard/server.log, probe /api/health for mode + uptime, check bridge WebSocket connectivity, triage vitest failures via tee→grep, inspect known-issue FAQ entries (Electron Node bin selection, Fastify + bad-Node crashes, stale-port hangs, single-instance lock). 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" / "the dashboard is doing Y" question.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Debug Dashboard when an AI agent needs a reusable SKILL.md workflow for this job: Diagnose problems in the running pi-agent-dashboard system. Tail /.pi/dashboard/server.log, probe /api/health for mode + uptime, check bridge WebSocket connectivity, triage vitest failures via tee→grep, inspect known-issue FAQ entries (Electron Node bin selection, Fastify + bad-Node crashes, stale-port hangs, single-instance lock). 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" / "the dashboard is doing Y" question.
When not to use it
Skip Debug Dashboard when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/debug-dashboard # Save SKILL.md to ~/.claude/skills/debug-dashboard/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/debug-dashboard/SKILL.md. For a shared project, commit the folder at .claude/skills/debug-dashboard/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Debug Dashboard skill for this task: Use Debug Dashboard when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 61/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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
```bash 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
| Symptom | Likely cause | Where to look | |---------|--------------|---------------| | Restart loops | Stale port held by zombie, or `restart` racing with bridge auto-start | `lsof -i :8000`, then `pi-dashboard stop` (kills by port, not just PID) | | `EADDRINUSE` on start | Concurrent spawn from multiple pi sessions | Harmless — losing process exits silently. Check log. | | Bridge connects then disconnects | `server_restarting` broadcast active, or version skew | grep `server_restarting` in server.log; check `/api/health` for version | | Blank page in browser | Vite not running in dev mode (silent fallback to prod build); or auth blocking | Check `/api/health.mode`; check `auth` settings | | New session won't start / yellow `spawn_register_timeout`, no card | `pi` crashed at startup (bad extension) OR host overload | See `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 boot | `launchDashboardServer` fell back to `process.execPath` (Electron GUI binary) | See `references/known-issues.md` → "Electron Node bin selection" | | Fastify crashes immediately | Bad 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`](references/known-issues.md).
## When tests fail mysteriously
Use the tee→grep pattern. Never rerun to inspect — capture once, grep forever:
```bash 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`](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`](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`](references/isolated-verification.md).
## Log file locations
All log + config files. Worth bookmarking. See [`references/log-locations.md`](references/log-locations.md) for the full map.
| Path | Contents | |------|----------| | `~/.pi/dashboard/server.log` | Daemon stdout/stderr, append mode, timestamped headers per start | | `~/.pi/dashboard/server.pid` | PID file (may be stale; use `lsof -i :8000` to confirm) | | `~/.pi/dashboard/config.json` | Live config (port, piPort, auth, tunnel, plugins) | | `~/.pi/dashboard/zrok.pid` | Tunnel PID file | | `~/.pi/dashboard/model-proxy.jsonl` | Model proxy request log (50 MB rotation) | | `~/.pi/dashboard/tool-overrides.json` | Tool registry overrides | | `/tmp/pi-test.log` | Last test run (when you used the tee→grep pattern) | | `~/.pi/agent/sessions/` | Per-session pi state |
## STOP — docs-first gate
Before answering any "how do I X" / "why does Y happen" question:
```bash grep -ni '<keyword>' docs/faq.md docs/*.md README.md ```
The FAQ already documents most recurring symptoms (Electron Node bin, Fastify crash range, tunnel watchdog, port conflicts). Reading source before grepping docs wastes tokens and risks wrong answers. Per `AGENTS.md` "STOP — Docs-First Gate".
## Related skills
- `browser` — UI/visual issues, screenshots, console errors, responsive testing (Electron + web) - `implement` — back to implementing once the bug is identified - `pi-dashboard` — interact with the dashboard via REST (list sessions, send prompts, abort) - `ci-troubleshoot` — when the problem only shows up in CI - `code-review` — review the fix before committing
Intended uses
- Use Debug Dashboard when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.