# pi-context-analyzer

A [Pi](https://pi.dev) extension that analyzes current context usage — similar to
Claude Code's context meter, with a section-level breakdown.

## Features

- **`/context`** — overview: model, context window, used/remaining tokens,
  auto-compaction threshold (with a progress bar), plus an **estimated
  breakdown by section**:
  - **System prompt** — custom prompt, guidelines, tool snippets, context
    files (AGENTS.md etc.), skills
  - **Messages** — by role (user / assistant / tool results / compaction summary)
  - **Tools** — builtin vs extension (MCP tools registered by extensions land
    here; pi has no built-in MCP support)
- **`/context skills`** — scrollable list of all loaded skills, sorted by
  estimated prompt footprint
- **`/context tools`** — scrollable list of all registered tools with their
  source, sorted by estimated definition size
- **`/context files`** — list of loaded context files

Sizes are **estimates** using pi's own `chars/4` heuristic
(`estimateTokens`). The provider's tokenizer may differ slightly; `/context`
shows a reconciliation line vs the provider-reported total.

## Install

```bash
pi install npm:pi-context-analyzer
```

Then run `/reload` and use `/context`.

## Requirements

- pi with extension support
- No npm dependencies; the extension only imports pi's bundled core packages
  (`@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`), declared as
  peer dependencies.

## Notes

- `reserveTokens` defaults to 16384 (pi's compaction default). If you changed
  `compaction.reserveTokens` in `settings.json`, the threshold marker in the
  overview will be slightly off — an override hook could be added later.

## Development

```bash
# run from source without installing
pi -e ./index.ts

# run the unit tests (zero deps, requires bun)
npm test

# publish a new version
npm version patch && npm publish

# test the published package
pi install npm:pi-context-analyzer
```

## Structure

`index.ts` is a thin registration stub; the implementation lives in `src/`:

- `src/command.ts` — subcommand routing + output-sink selection (tui/json/print/notify)
- `src/breakdown/` — per-section collectors (system prompt / messages / tools),
  pure functions unit-tested in `test/`
- `src/report.ts` — renders the overview report as plain text
- `src/ui/` — TUI panels (static panel, scrollable list)
- `src/format.ts`, `src/estimate.ts`, `src/types.ts` — pure helpers and data model;
  `estimate.ts` is the seam for a future real tokenizer

## License

MIT