@prjct.app/pi-doctor

Local health checks and scoped performance observations for Pi extensions, compact active-model value advice and confirmed management actions.

Packages

Package details

extension

Install @prjct.app/pi-doctor from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@prjct.app/pi-doctor
Package
@prjct.app/pi-doctor
Version
0.4.0
Published
Oct 13, 2026
Downloads
840/mo · 12/wk
Author
jlopezlira
License
MIT
Types
extension
Size
1.7 MB
Dependencies
1 dependency · 2 peers
Pi manifest JSON
{
  "image": "https://raw.githubusercontent.com/prjct-app/pi-doctor/main/docs/cover.png",
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-doctor

pi-doctor — for PI Agent

Check extension health, activation and observed impact in the existing shared panel. Optional active-model advice evaluates workflow value using compact facts and evidence fetched on demand.

Available in npm 0.4.0. Complete live diagnostics and isolated profiling remain gated.

Commands

Command Action
/doctor Open the shared panel; press s for a quick check.
/doctor scan Check local metadata without reading README/source/skill bodies.
/doctor deep Explicitly inspect disk, dependencies, source candidates and skill instructions.
/doctor observe N Observe tool metadata and global process metrics for 1–120 seconds; default 30.
/doctor profile Show the blocked isolated-profiler prerequisite; execute no inspected code.
/doctor analyze [extensions|skills|all|rN] Confirm compact value advice for the selected scope; default extensions.
/doctor cancel Cancel the Doctor operation; retain collected facts.
/doctor report Print the same audit details as text.

Panel controls: s check, a advise on the selected resource (overview selects extensions), b cancel, t observe, p profiling eligibility, f filter, o sort, / search and v switch to management. The shared TUI handles navigation, detail focus, help and closing.

In management: e enable, d disable, x uninstall a package and c clean backup/disabled files. Destructive actions require confirmation and back up settings first. Run /reload after changing extension loading.

Measurements and analysis

  • Package/resource logical bytes exclude node_modules and .git; resolved runtime dependencies form a separate graph deduplicated by physical path.
  • Skill catalog advertisement, potential instruction load and retained direct instruction/reference reads are separate.
  • Tool declarations are estimated before provider/loadout transforms. Tokens use characters / 4; dynamic injection and indirect reads can remain unknown.
  • Discovery uses configured packages, effective SDK skills and runtime capability metadata. Excluded resources and hook-only extensions may be undiscoverable.
  • Analysis reads bounded resource excerpts and current session context, not global histories or auth files. Private filenames are excluded and common secrets redacted. Resource text is untrusted evidence.
  • Health distinguishes passed local checks, failures and unchecked runtime coverage. Excluded configuration, deferred tools and zero calls do not establish zero impact.
  • Observation records counts/errors and top-level execute durations, not arguments or result bodies. CPU/RSS/heap/event-loop measurements describe the whole Pi process, not an extension's exclusive cost. Errors are not automatically defects.
  • Analysis preserves ordinary declarations, adds advice tools and blocks other execution. Steering/cancellation restores the prior tools. Recommendations never change configuration. Each digest is capped at 8,000 UTF-8 bytes; the successful Doctor-added payload budget is 32,000 bytes, not a provider billing/output cap.
  • Full live hook/import/error attribution requires a supported host diagnostics bridge. Executable A/B profiling requires an approved whole-process sandbox and fixtures; this candidate provides neither and reports the gates as blocked.

Stored management data

~/.prjct/pi-doctor/backups/ holds operation backups. ~/.prjct/pi-doctor/manifest.sqlite records removal origin, SHA-256, backup path and time. Audit facts and recommendations remain session-local.

Development

npm run check
npm test

Tests use temporary fixtures. See the health design and implementation ticket.