pi-token-burden

See where your system prompt tokens go.

A pi extension that parses the assembled system prompt and shows a token-budget breakdown by section. Run /token-burden to see how much of your context window is consumed by the base prompt, AGENTS.md files, skills, SYSTEM.md overrides, and metadata.

Install

pi install npm:pi-token-burden

Or from git:

pi install git:github.com/Whamp/pi-token-burden

To try it for a single session without installing, use pi -e npm:pi-token-burden.

Requirements

• pi v0.55.1 or later

Usage

Type /token-burden in any pi session. An overlay appears with a stacked bar and a drill-down table:

What each section measures

| Section | Content | | -------------------------------- | ---------------------------------------------------------------- | | Base prompt | pi's built-in instructions, tool descriptions, guidelines | | SYSTEM.md / APPEND_SYSTEM.md | Your custom system prompt overrides | | AGENTS.md files | Each AGENTS.md file, listed individually | | Skills | The <available_skills> block, with per-skill breakdown | | Metadata | The Current date and time / Current working directory footer |

Token estimation

Tokens are counted using gpt-tokenizer with the o200k_base encoding (used by GPT-4o, o1, o3, and other modern models). This gives exact BPE token counts rather than a character-based approximation.

Development

git clone https://github.com/Whamp/pi-token-burden.git
cd pi-token-burden
pnpm install
pnpm run test     # 21 tests
pnpm run check    # lint, typecheck, format, dead code, duplicates, tests

Test locally: pi -e ./src/index.ts, then type /token-burden.

Contributing

Contributions are welcome. Please open an issue before starting work on larger changes.

Changelog

See CHANGELOG.md for release history.

License

MIT