---
slug: "tianzong48-pi-doctor-extension"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/t1anz0ng/pi-doctor@main/README.md"
repo: "https://github.com/t1anz0ng/pi-doctor"
source_file: "README.md"
branch: "main"
---
# 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`.

```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:

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

Install from npm:

```bash
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:

```text
/doctor-startup
```

`/doctor-startup` launches a nested child process:

```bash
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

```text
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

```text
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

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