pi-context-viz

Interactive context window visualizer for pi — colored grid overlay with token breakdown, stats, and optimization suggestions

Packages

Package details

extension

Install pi-context-viz from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-context-viz
Package
pi-context-viz
Version
1.0.0
Published
May 22, 2026
Downloads
not available
Author
viartemev
License
MIT
Types
extension
Size
41.1 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-context-viz

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

screenshot

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