# 📊 pi-context-breakup

[![npm version](https://badge.fury.io/js/pi-context-breakup.svg)](https://www.npmjs.com/package/pi-context-breakup)

A [pi](https://github.com/mariozechner/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)

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

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

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

### Via git

```bash
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):

```bash
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`:

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

## Requirements

- [pi](https://github.com/mariozechner/pi) coding agent

## Development

See [DEVELOPMENT.md](DEVELOPMENT.md) for local development, testing, and publishing instructions.

## License

MIT