Pixie Doctor

Pixie installation health check

You are checking the Pixie installation itself — the host, not any one tool. This skill never modifies anything. It runs a fixed sequence of diagnostics and reports a markdown summary with a recommended-fixes list at the end.

Routing check (do this first)

• If the user wants to know what Pixie is currently DOING (warm tools, uptime), switch to pixie-status.
• If the user is reporting a single failing tool, switch to debug-tool.
• If the user wants a per-tool list with cached validation status, switch to list-tools.

Pre-flight: read the kill file

Before doing anything that might touch existing patterns, read .build/KILL_FILE.md. Any entry whose Context or Symptom matches your current task -> apply the documented Fix directly, do not re-debug from scratch.

Steps

1. Check Python version

uv run python --version

Pass if >= 3.12. Fail otherwise.

2. Check uv is installed and recent

uv --version

Pass if present. Warn if older than 0.4.0.

3. Check Pixie's own dependencies import

uv run python -c "import fastapi, uvicorn, httpx, pydantic, jinja2, typer, rich; print('ok')"

Pass if "ok". Fail with the import error otherwise — recommend uv sync at the repo root.

4. Check pixie.db is readable

uv run python -c "
import sqlite3, pathlib
db = pathlib.Path('pixie.db')
if not db.exists():
    print('MISSING'); raise SystemExit
con = sqlite3.connect(db)
tables = [r[0] for r in con.execute(\"SELECT name FROM sqlite_master WHERE type='table'\").fetchall()]
print('tables=' + ','.join(tables))
"

MISSING is a warn, not a fail (db is created on first run). Fail only if the file exists but is corrupt.

5. Check tools/ folder readable

ls tools/ 2>&1

Fail if not readable. Warn if empty (no tools installed).

6. Check each tool's .venv

uv run python -c "
import pathlib, sys
results = []
for tool in sorted(pathlib.Path('tools').iterdir()):
    if not tool.is_dir() or not (tool/'tool.json').exists():
        continue
    venv = tool/'.venv'
    if not venv.exists():
        results.append((tool.name, 'MISSING'))
        continue
    py = venv/'Scripts'/'python.exe' if sys.platform == 'win32' else venv/'bin'/'python'
    results.append((tool.name, 'OK' if py.exists() else 'INCOMPLETE'))
for name, status in results: print(f'{name}\t{status}')
"

Render as a table. Recommend cd tools/<id> && uv sync for any MISSING or INCOMPLETE row.

7. Check each tool's latest validation status (from pixie.db, no re-run)

uv run python -c "
import sqlite3, pathlib
db = pathlib.Path('pixie.db')
if not db.exists(): raise SystemExit
con = sqlite3.connect(db)
rows = con.execute('SELECT tool_id, overall, MAX(timestamp) FROM validation_reports GROUP BY tool_id').fetchall()
for r in rows: print(f'{r[0]}\t{r[1]}\t{r[2]}')
"

Render as a table. Recommend revalidate-all if any tool's report is older than 14 days, or if there are tools on disk with no report at all.

8. Check disk space

uv run python -c "
import shutil, pathlib
total, used, free = shutil.disk_usage(pathlib.Path('.'))
gib = lambda n: n / (1024**3)
print(f'free={gib(free):.2f} GiB total={gib(total):.2f} GiB')
"

Warn if free < 1 GiB. Fail if free < 100 MiB.

9. Check port 7860 status

uv run python -c "
import socket, os
port = int(os.environ.get('PIXIE_PORT', '7860'))
s = socket.socket()
try:
    s.bind(('127.0.0.1', port))
    print(f'FREE port={port}')
except OSError:
    print(f'IN_USE port={port}')
finally:
    s.close()
"

If IN_USE, hit /api/healthz to see if it's Pixie:

uv run python -c "
import httpx, os
port = os.environ.get('PIXIE_PORT', '7860')
try:
    r = httpx.get(f'http://127.0.0.1:{port}/api/healthz', timeout=2.0)
    print('PIXIE' if r.status_code == 200 else 'OTHER')
except Exception:
    print('OTHER')
"

PIXIE is fine. OTHER is a fail — another process is squatting on the port.

10. Render the final report

Combine all sections under ## Pixie installation health. Each subsection has a single-line status: PASS, WARN, or FAIL. End with a ## Recommended fixes list — one bullet per actionable finding, in priority order (FAILs first, then WARNs). Plain shell commands the user can copy.

If everything passes:

"Pixie installation is healthy. No action required."

On failure: append to the kill file

If you encounter an error NOT already in .build/KILL_FILE.md, append a new entry with the next KILL-NNNN id following the schema. Be terse -- root cause + one-line fix + one-line rule.

Do NOT

• Do NOT run uv sync automatically — recommend it, let the user run it.
• Do NOT run the validator on any tool — use cached reports only. Recommend revalidate-all if needed.
• Do NOT modify pixie.db, tool.json, or any source file.
• Do NOT start or stop Pixie processes.
• Do NOT bind to 0.0.0.0 or any non-loopback interface during port checks.
• Do NOT add Docker, container, or cloud-deployment files.
• Do NOT invoke other Pixie skills programmatically. Offer the user a choice and stop.

Source: AlexKapadia/Pixie — distributed by TomeVault.