pi-health-check
v0.1.2
Published
Startup diagnostics for the pi extension ecosystem: detect missing dependencies, duplicate packages, and skills referencing unregistered tools.
Maintainers
Readme
pi-health-check
Startup diagnostics for the pi extension ecosystem.
Detects missing dependencies, duplicate packages, and skills that reference unregistered tools — before they cause silent failures or startup crashes.
What it detects
| # | Check | Severity | Description |
|---|-------|----------|-------------|
| 1 | Missing dependency | error | Extension package.json declares a dependency that is not installed in node_modules |
| 2 | Duplicate package | warning/error | Same package loaded from multiple paths (same version = warning, different versions = error) |
| 3 | Missing skill tool | warning | Skill frontmatter requires-tools declares a tool that is not registered |
| 4 | Possible missing tool | info | Skill body mentions a known optional tool name (e.g. subagent) that is not registered |
Install
pi install npm:pi-health-checkOr from git:
pi install git:github.com:fengshuai/pi-health-check.gitUsage
The extension activates automatically on session start. Three entry points:
1. Startup notification
If issues are found, a one-line warning appears at startup:
Warning: pi-health-check: 12 errors. Run /doctor for details.2. /doctor command (interactive TUI)
/doctorRenders a scrollable report with severity icons, affected paths, and fix suggestions:
✗ pi-health-check diagnostics report
Found: 12 errors
12 diagnostics total
✗ Missing dependency
Extension "pi-subagents" requires npm package "jiti" but it is not installed.
Extension: /home/user/.pi/agent/npm/node_modules/pi-subagents/index.ts
Expected at: .../node_modules/jiti
-> Run: cd "..." && npm install
Press Enter/Esc to close · j/k to scroll3. doctor tool (LLM-callable)
The LLM can call the doctor tool when it encounters a "tool not found" error, to self-diagnose the ecosystem and get a structured report.
Skill dependency declaration
Skills can declare required tools in frontmatter:
---
name: my-skill
description: ...
requires-tools: [subagent, mcp__context7]
---
Skill body...The checker validates these against the registered tool set. Supports glob patterns (mcp__*).
What it does NOT do
- Does not auto-fix or auto-install anything (only reports + suggests commands)
- Does not modify pi core or settings
- Does not send data anywhere (purely local filesystem scan)
How it works
The extension reads the filesystem directly (~/.pi/agent/extensions/, .pi/extensions/, ~/.pi/agent/skills/, .pi/skills/, npm node_modules dirs) and compares against pi.getAllTools(). No resourceLoader API dependency.
License
MIT
