pi-context-viz

Interactive context window visualizer for pi — a colored overlay showing token usage breakdown, session stats, and optimization suggestions.

Features

• Colored grid — visual breakdown of context window by category
• Progress bar — at-a-glance usage overview
• 3 view modes — Grid (default), Table (T), Detail (Enter)
• Interactive navigation — arrow keys / jk to browse categories, Enter for details
• Remaining turns estimate — how many more turns before compaction needed
• Cost projection — current cost + projected cost for full context
• Session history — trend of context usage across /context invocations
• Smart warnings — context >80%, tools >25%, thinking >40%, compaction bloat
• Compact mode — auto-adapts for narrow terminals (<60 cols)
• Save report — S copies a text report to clipboard

Categories tracked

| Category | Description | |----------|-------------| | System Prompt | Estimated system prompt tokens | | User Messages | All user input tokens | | Assistant Text | Model output (excluding thinking) | | Thinking | Hidden reasoning tokens | | Tool: read/bash/edit/… | Tool result tokens, per tool | | Compaction | Compaction summary tokens | | Custom Messages | Injected/custom message tokens | | Images | Estimated image tokens | | Free | Available context space |

Install

pi install git:github.com/viartemev/pi-context-viz

Or try without installing:

pi -e git:github.com/viartemev/pi-context-viz

Usage

Type /context in pi to open the overlay.

Keybindings

| Key | Action | |-----|--------| | ↑ ↓ / j k | Navigate categories | | Enter | Show category details | | T | Toggle table/grid view | | S | Save report to clipboard | | Esc / q | Close overlay |

Detail mode

Pressing Enter on a category shows:

• Tools: call count, avg tokens/call, max call size
• User/Assistant: message count, text vs thinking split
• Images: image count
• Free: estimated remaining turns

How it works

1. Iterates the session branch to extract message types and tool calls
2. Estimates tokens using ~4 chars/token heuristic (consistent with pi's estimator)
3. Uses ctx.getContextUsage() for accurate total when available
4. Renders as an interactive TUI overlay via ctx.ui.custom()

License

MIT