pi-context-usage

A pi extension package that adds:

• /context — a dot-grid visualization of current context usage
• /context details — a deeper breakdown of system prompt, active tools, and conversation turns

DEMO:

Install

As a pi package

pi install pi-context-usage

Manual (project-local)

Copy or symlink this directory into .pi/extensions/pi-context-usage/.

Check out my other Pi extensions

• — Auto-syncs Pi theme with OS dark/light mode.
• — Real-time prompt cache hit rates and token metrics.
• — Session task checklist with dependencies and a TUI renderer.
• — Prunes verbose tool outputs from context while preserving history.
• — Dot-grid visualization of context window token usage.
• — Live tokens/sec and TTFT in the status bar.
• — Tracks subscription quotas and rate limits across AI providers.

Usage

Context summary

/context

Shows a dot-grid summary with five breakdown categories:

Context Usage

◍ ⚙ ● ● ● ● ● ● ● ● ●
● ● ● ● · · · · · · ·
· · · · · · · · · · ·
· · · · · · · · · · ·
· · · · · · · · · · ·
· · · · · · · · · · ·
· · · · · · · · · · ·
· · · · · · ○ ○ ○ ○ ○

claude-sonnet-4-5   31.4k / 200.0k tokens (16%)

◍ System Prompt:    1.7k (1%)
⚙ Tools:              275 (0%)
● Messages:        29.4k (15%)
· Empty:           152.2k (76%)
○ Buffer:           16.4k (8%)

Context details

/context details

When UI is available, this opens a keyboard-driven overlay that keeps the grid summary at the top and adds expandable sections for:

• System Prompt — visible estimate from ctx.getSystemPrompt(), split into independently expandable introduction and Pi's <tools>, <rules>, <docs>, <project_context>, <skills>, <cwd>, and other named sections. Each part shows its own estimated tokens and characters; expanding it reveals its text. Available Skills expands into one row per advertised skill; each row shows its estimated prompt tokens, total serialized characters (including markup and location), and the separate character counts for its name and description. Expand a skill to read its description. These counts reflect the escaped text in the prompt, not the contents of skill files.
• Tools — active tool schema breakdown from pi.getAllTools() filtered by pi.getActiveTools() (separate from the <tools> prompt instructions)
• Conversation — one line per user turn, plus inline compaction summaries and per-message drill-down

Keyboard shortcuts in the overlay:

• ↑/↓ move focus
• Enter or → expand a section/row
• ← collapse a section/row
• Tab jump between top-level sections
• PageUp/PageDown, Home/End scroll faster
• Esc or q close

When UI is not available, /context details falls back to a plain-text dump.

Example plain-text output:

System / Tools Details

Item                Tokens  Chars
System prompt         6.2k  24,800
read                    70     279
bash                    61     244
edit                   142     567
Total visible parts    6.5k  25,890

Note: visible parts sum to 2.2k tokens, while the top summary uses 14.3k cached prompt tokens from the last assistant cache. That cache number includes provider-side scaffolding and cached context that extensions cannot inspect.

Conversation (6 turns)
Per-turn and cumulative values are visible-entry estimates from estimateTokens(message); they will not match the summary's provider/cache totals.

 #1  10:00  U  Can you inspect the repo and summarize how /context currently works?      55      55 cum est
 #2  10:01  U  Now sketch a plan for a /context details mode with a deeper breakdown.      36      91 cum est
  Σ  10:06  Σ  Earlier discussion established the design…      38     197 cum est
 #3  10:10  U  Add the system prompt and active-tools breakdown next.      65     262 cum est

Development

# Load extension directly into a live pi session
pi -e ./src/index.ts

# After sending at least one message
/context
/context details

# Standalone mock tests
bun run test:mock
bun run test:mock-details

How it works

Summary buckets

Category	Symbol	Theme color	Token source
System Prompt	◍	accent	Math.ceil(systemPrompt.length / 4) — estimated from visible system prompt text
Tools	⚙	muted	Sum of Math.ceil((name + description + JSON.stringify(parameters)).length / 4) over active tools
Messages	●	success	usedTokens - systemPromptTokens - toolTokens — conversation entries
Empty	·	dim	contextWindow - usedTokens - bufferTokens — unused space
Buffer	○	warning	model.maxTokens — reserved for model output

All visible estimates use a chars / 4 heuristic. The grid distributes cells proportionally across the five categories.

Details view estimates

• System prompt tokens: Math.ceil(systemPrompt.length / 4)
• Per-tool tokens: Math.ceil((name + description).length / 4) + Math.ceil(JSON.stringify(parameters).length / 4)
• Turn tokens: summed via pi's exported estimateTokens(message) heuristic

Because pi does not expose the exact provider-serialized request payload, the visible system prompt + tools total is intentionally labeled as an approximation. The cache-provided number in details remains the authoritative cached-prompt value, and it is not directly comparable to the visible estimates.