@that-yolanda/pi-context

Context window usage visualization for PI coding agent.

Packages

Package details

extension

Install @that-yolanda/pi-context from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@that-yolanda/pi-context
Package
@that-yolanda/pi-context
Version
0.2.1
Published
May 15, 2026
Downloads
384/mo · 30/wk
Author
that-yolanda
License
MIT
Types
extension
Size
970.7 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

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

README

pi-context

Context window usage visualization command for PI coding agent. Shows a token grid with category breakdown.

Usage

Run /context in PI to display the overlay. Press any key to close.

Architecture

Registers a single command context via pi.registerCommand().

Token estimation

Uses a simple length / 4 heuristic to estimate token counts. The raw estimates are then scaled by a ratio (totalActual / totalRaw) to match the actual token count reported by the agent.

Visualization

  • Token grid: 10×5 block grid where each block represents a proportional share of the context window
  • Category breakdown: Shows system prompt, tool definitions, tool calls, messages, available space, and auto-compact reserve
  • Session Token Usage: Input tokens (miss + cache hit with rate), output tokens from the API usage field
  • Colors: Each category has a fixed color (muted, warning, accent, dim, text)

Key functions

  • getReserveTokens(cwd) — reads reserveTokens from .pi/settings.json or ~/.pi/agent/settings.json
  • formatTokens(n) — formats token counts as N/A, 1k, 1.5M (in utils.ts)

Testing

Tests for formatTokens are in __tests__/utils.test.ts.

cd pi-context && pnpm test

Changelog

See CHANGELOG.md.