pi-context-breakup

A Pi extension that breaks down your context window into categories and shows exactly what's consuming your tokens.

Features

• 7 categories of context breakdown:

  • System Prompt — Pi's base instructions
  • Rules — Guidelines and behavioral rules
  • Tool Set Output — Non-MCP tool descriptions
  • MCP — MCP server tools taking up space
  • Skills — Loaded agent skills
  • User Context — AGENTS.md / context files
  • User Input — Conversation history

• Tabular display with token counts, percentages, and visual progress bars

• Overlay UI — appears on top of your chat without clearing the screen

• Print mode fallback — works in -p / --print mode too

Installation

Via npm (recommended)

pi install npm:pi-context-breakup

Project-local

git clone https://github.com/imran-vz/pi-context-breakup.git
cd pi-context-breakup
npm install
npm run dev:link

Temporary test

pi -e ./extensions/pi-context-breakup.ts

Usage

Once installed, type in Pi's editor:

/context-breakup

An overlay will appear showing:

┌──────────────────────────────────────────────────────────┐
│                📊 Context Window Breakdown                │
├──────────────────────────────────────────────────────────┤
│ Category           Tokens      %     Bar                 │
│ ──────────────────────────────────────────────────────── │
│ System Prompt        2843   42.3%  [██████░░░░░░░░]      │
│ Rules                 412    6.1%  [█░░░░░░░░░░░░░]      │
│ Tool Set Output      1521   22.6%  [███░░░░░░░░░░░]      │
│ MCP                   890   13.2%  [██░░░░░░░░░░░░]      │
│ Skills                320    4.8%  [█░░░░░░░░░░░░░]      │
│ User Context          180    2.7%  [░░░░░░░░░░░░░░]      │
│ User Input            560    8.3%  [█░░░░░░░░░░░░░]      │
│ ──────────────────────────────────────────────────────── │
│ System Prompt        2843   42.3%                          │
│ Messages              560    8.3%                          │
│ Total / Window     6726 / 200000  (3.4%)                 │
├──────────────────────────────────────────────────────────┤
│         Press Enter or Esc to close                      │
└──────────────────────────────────────────────────────────┘

Press Enter or Escape to dismiss.

How It Works

The extension hooks into Pi's lifecycle events:

• before_agent_start — captures the structured system prompt options (tools, guidelines, skills, context files)
• context — captures the conversation messages

It then reconstructs each section of the system prompt exactly as Pi builds it, estimates tokens using Pi's own chars/4 heuristic, and renders the breakdown.

Customization

MCP tools are detected heuristically by name (containing mcp or starting with dokploy_mcp). If you use a different MCP prefix, edit the filter in extensions/pi-context-breakup.ts:

const mcpVisibleTools = visibleTools.filter(
  (name) =>
    name.toLowerCase().includes("mcp") ||
    name.toLowerCase().startsWith("your-prefix-here"),
);

Development

See DEVELOPMENT.md for local development, testing, and publishing instructions.

License

MIT