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