📊 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

Or add it to your project's package.json under the pi.extensions array:

{
  "pi": {
    "extensions": ["npm:pi-context-breakup"]
  }
}

Via git

pi install git:github.com/imran-vz/pi-context-breakup

Manual

Copy the extension file to ~/.pi/agent/extensions/ (or .pi/extensions/ for project-local):

cp extensions/pi-context-breakup.ts ~/.pi/agent/extensions/

Commands

Command	Description
/context-breakup	Show context window breakdown overlay with token counts and percentages

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"),
);

Requirements

• pi coding agent

Development

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

License

MIT