pi-doctor

Pi diagnostics package. The first diagnostic area is startup timing and skill path hygiene.

Pi package shape

pi-doctor follows the Pi package convention: Pi loads runtime behavior from the pi manifest in package.json.

{
  "pi": {
    "extensions": ["./extensions/pi-doctor/index.ts"]
  }
}

There is intentionally no runtime bin entry. Diagnostics are exposed as Pi slash commands instead of standalone shell commands.

Install

Install a local checkout:

pi install /Users/bytedance/dev/pi-doctor

Install from npm:

npm_config_registry=https://registry.npmjs.org pi install npm:@tianzong48/pi-doctor-extension

Use the explicit registry when your npm default points at an internal mirror such as bnpm.byted.org.

Command

Run the startup doctor:

/doctor-startup

/doctor-startup launches a nested child process:

pi --no-session -p "/doctor-startup-marks"

It then reports:

• child pi process wall-clock startup time
• nested extension-visible startup marks
• slow startup warnings
• slow lifecycle step warnings
• broken skill symlinks under known skill roots

/doctor-startup-marks is an internal helper used by the nested process.

Example output

Pi Doctor startup report

- command: pi --no-session -p /doctor-startup-marks
- process_total: 1636.1ms
- status: exit=0
- output_bytes: 306

Nested startup marks

Pi Doctor startup timing

- module_loaded: step +0.0ms, total +0.0ms — pi-doctor module evaluated
- factory_called: step +0.1ms, total +0.1ms — extension factory entered
- session_start: step +82.9ms, total +83.0ms — reason=startup
- resources_discover: step +0.1ms, total +83.1ms — reason=startup

Skill path checks

⚠️ Found 8 skill path issues:
- broken symlink: ~/.agents/skills/example — target=/missing/path; Error: ENOENT...

Warning thresholds

• process_total >= 5s: marked ⚠️ SLOW
• process_total >= 10s: marked 🚨 VERY SLOW
• lifecycle step >= 1s: marked ⚠️ SLOW STEP

Current observability boundary

A Pi extension cannot observe time before Pi discovers and evaluates that extension. process_total covers the full nested child process, while nested startup marks cover only the extension-visible lifecycle inside that child.

Startup work before module_loaded may include:

• Node.js process startup
• Pi CLI argument parsing
• settings loading
• package discovery
• extension path resolution
• dependency loading before this module is evaluated
• provider/model registry initialization that happens before extension loading

To diagnose finer-grained cold-start latency later, add a Pi core timing hook in pi-mono before settings/package/provider/resource initialization, then expose those marks to extensions or a debug command.

Source layout

extensions/pi-doctor/
├── index.ts            # Pi extension entrypoint and lifecycle wiring
├── launcher-probe.ts   # nested pi process startup measurement
├── output.ts           # UI vs print-mode output helper
├── skill-paths.ts      # skill root and broken symlink diagnostics
├── startup-report.ts   # text report rendering
└── startup-timing.ts   # timing mark data model and recorder

Development

cd /Users/bytedance/dev/pi-doctor
npm install
npm run check
pi --no-session -p "/doctor-startup"