Przejdź do treści
Biblioteka skilli
DevOps i chmura · Analiza

debug-dashboard

/debug-dashboard

Diagnozuje problemy działającego systemu pi-agent-dashboard: server.log, /api/health, połączenia WebSocket mostu, testy vitest, puste strony, pętle restartów i konflikty portów.

Licencja
MIT
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
19
Skrypty
4
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 4 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/health-probe.ts, scripts/list-sessions.ts, scripts/run-tests-triage.ts, scripts/tail-server-log.ts

Co robi i kiedy

Diagnozuje problemy działającego systemu pi-agent-dashboard: server.log, /api/health, połączenia WebSocket mostu, testy vitest, puste strony, pętle restartów i konflikty portów.

Wyzwalacze z opisu

why isnt X working
Oryginalny opis (EN)

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.

Jak działa

  1. First moves — always run these
  2. When the server is up but misbehaving
  3. When tests fail mysteriously
  4. When the UI is the problem
  5. When you must verify a change without touching the live server
  6. Log file locations
  7. STOP — docs-first gate
  8. Related skills
Sekcje z nagłówków SKILL.md, w oryginale · 102 linii, 886 słów
Podgląd SKILL.md
---
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:

```mermaid
flowchart TD
  L1["Layer 1 - Is the server alive?<br/>npx tsx ./scripts/health-probe.ts<br/>npx tsx ./scripts/tail-server-log.ts"]
  L2["Layer 2 - Are the bridges connecting?<br/>npx tsx ./scripts/list-sessions.ts<br/>npx tsx ./scripts/tail-server-log.ts --errors"]
  L3["Layer 3 - Is the UI rendering?<br/>(use the browser skill)"]
  L1 --> L2 --> L3
```

## 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 owned port holders, not just PID; `--force` is a dangerous last resort, see known-issues.md) |
| `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 |
| `server.log`: `PI_DASHBOARD_TS_LOADER is no longer supported` | Legacy env var set; server ignores it (jiti server loader removed) | Unset `PI_DASHBOARD_TS_LOADER` from launch env; `pi-dashboard stop && pi-dashboard start` |
| `server.log`: `server booted under the jiti TypeScript loader` | Pre-upgrade server handed its jiti `--import` on restart | `pi-dashboard stop && pi-dashboard start` (next restart normalizes to native) |

Loader launch recipes: server → native register (`platform/native-ts-register.mjs`); jiti only for pi-hosted code. See `node-inspect-debugger` skill, Tier 2 / Tier 2b.

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
Pliki w paczce (19)
  • SKILL.md 7 KB
  • SKILL.md.AGENTS.md 1 KB
  • references/isolated-verification.md 6 KB
  • references/known-issues.md 8 KB
  • references/known-issues.md.AGENTS.md 1 KB
  • references/log-locations.md 4 KB
  • references/log-locations.md.AGENTS.md 1 KB
  • references/test-failure-triage.md 4 KB
  • references/test-failure-triage.md.AGENTS.md 1 KB
  • references/ui-debug.md 2 KB
  • references/ui-debug.md.AGENTS.md 1 KB
  • scripts/health-probe.ts 4 KB
  • scripts/health-probe.ts.AGENTS.md 1 KB
  • scripts/list-sessions.ts 3 KB
  • scripts/list-sessions.ts.AGENTS.md 1 KB
  • scripts/run-tests-triage.ts 3 KB
  • scripts/run-tests-triage.ts.AGENTS.md 1 KB
  • scripts/tail-server-log.ts 3 KB
  • scripts/tail-server-log.ts.AGENTS.md 1 KB

Wersje

W bazie nie ma innych skilli o nazwie debug-dashboard.

Migawka bazy z 13.11.2026 · wersja paczki da068f90fdb8 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100health-check
    Przeprowadza kontrole kondycji systemu Claude Code Agent Monitor: API dashboardu, baza danych, WebSocket, hooki i zużycie dysku, by sprawdzić poprawność konfiguracji monitoringu.
  • 95docker-debug
    Diagnozuje Kurtosis działający na lokalnym Dockerze: logi, awarie kontenerów, konflikty portów i problemy z siecią.
  • 100dashboard-status
    Szybko sprawdza stan dashboardu Agent Monitor: API na porcie 4820, liczby sesji, agentów i zdarzeń, połączenie WebSocket, status hooków i świeżość danych.
  • 100debug-browser-session
    Diagnozuje sesję przeglądarki w chmurze Kernel: problemy z maszyną wirtualną, błędami sieci, awariami Chrome, ładowaniem stron i podglądem na żywo, korzystając z CLI Kernel.
  • 100network-health-check
    Wykonuje kontrolę kondycji sieci UniFi: stan urządzeń, problemy z łącznością, aktualizacje firmware i ogólny stan systemu.
  • 100ssh-diagnose
    Diagnozuje problemy zdalnego serwera, np. wolną pracę, awarię usługi, pełny dysk, obciążenie CPU, pamięci lub sieci.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.