pi-extension-times

pi-extension-times is a hybrid Pi package for measuring slow extension startup, explaining likely causes, and handing off a plan-first optimization session.

What it does

After installing the package, a Pi user can run /extension-times and get an interactive workflow:

• Pi opens a small overlay that says Measuring...
• the package profiles discovered extensions with a Pi-like createJiti -> jiti.import -> factory(api) sequence
• the overlay switches to a sorted results list from slowest to fastest
• rows above 100 ms are highlighted as warnings and rows above 500 ms are highlighted as critical
• pressing Enter on an extension opens a fresh analysis session with a seeded prompt, saved artifacts, and instructions to plan first before editing

The package also supports direct CLI and slash-command inspection flows for automation.

Why the package is hybrid

A normal Pi extension cannot fully observe the loader path that loaded itself, because Pi imports extensions before extension code gets control. This package therefore uses two cooperating pieces:

• a small Pi extension entrypoint for commands, UI, artifact handling, and session handoff
• an external profiling engine that mirrors Pi's startup sequence closely enough to collect useful timing data

See advice.md for the design notes that shaped the heuristics and recommendations.

Commands

Interactive Pi flow

Run Pi with the source entry during development:

pi -e ./src/index.ts

Inside Pi, use:

/extension-times

The default command opens the interactive measuring-and-results workflow.

Direct slash-command subcommands

These subcommands are useful when you want a saved report or an inspection without reopening the interactive picker:

/extension-times profile
/extension-times inspect #1
/extension-times analyze #1
/extension-times publish #1

#1 means the slowest extension from the latest saved profile. You can also pass an extension source label or path.

• profile reruns profiling and saves the latest report under .pi/extension-times/
• inspect runs the conservative static inspection engine and writes a Markdown summary to the editor
• analyze generates inspection and proposal artifacts, then opens a new plan-first session
• publish prepares safe Git and GitHub follow-up instructions without pushing anything automatically

CLI usage

Build first:

npm run build

Then run:

node ./dist/cli/profile.js --cwd ./test/fixtures/workspace --no-configured-packages
node ./dist/cli/inspect.js --cwd ./test/fixtures/workspace '#1'

The profile CLI writes a JSON report and summary under .pi/extension-times/. Use --no-configured-packages when you want to profile only the local fixture or repository extensions without enabled packages from your Pi settings. The inspect CLI reads the latest profile and emits a Markdown inspection plus proposal summary.

Artifact layout

Reports and follow-up artifacts are stored inside the active project:

.pi/extension-times/
  latest.json
  latest-inspection.json
  latest-proposal.json
  reports/<timestamp>/profile.json
  reports/<timestamp>/summary.md
  inspections/<timestamp>/<extension-id>.json
  inspections/<timestamp>/<extension-id>.md
  proposals/<timestamp>/<extension-id>.json
  proposals/<timestamp>/<extension-id>.md
  handoffs/<timestamp>/<extension-id>.md

Keeping artifacts next to the analyzed repository makes it easy to inspect, compare, or clean them up later.

Heuristics implemented today

The inspection engine currently looks for the highest-value startup smells from advice.md:

• large local import graphs
• eager provider registries
• top-level UI or manager imports on the startup path
• synchronous filesystem work during startup
• heavy third-party dependencies imported eagerly The analysis stays conservative and path-based. It is designed to produce actionable advice such as moving a manager screen behind import() or delaying synchronous file scanning until first use.

Approval model

The package does not auto-edit third-party code. Instead it prepares a plan-first handoff:

1. profile the extension
2. inspect the import graph and startup smells
3. generate safe behavior-preserving optimization proposals
4. open a fresh Pi session with artifact paths and explicit instructions to plan first
5. wait for user approval before any edits happen
6. suggest publishing only after checks pass and the user confirms the extension still works

Local development

Install dependencies:

npm install

Validate the package:

npm run check
npm run test
npm run build
npm run profile:fixtures
npm run inspect:fixtures

Publishing notes

The published package points Pi at ./dist/index.js, not the raw TypeScript source. During local development you can still run pi -e ./src/index.ts.