pi-cache-graph

A project-local pi extension that adds cache inspection commands for monitoring LLM context cache usage.

This extension was built primarily to add observability to the pi-context-prune extension — which compacts the session context to keep token usage down. pi-cache-graph lets you see in real time how effectively the cache is being used and how pruning affects cache hit rates over a session.

Adds cache inspection commands:

• /cache graph — shows cache hit % over time for assistant turns across the current session timeline
• /cache stats — shows per-message token/cache breakdown for assistant messages across the whole session tree, plus cumulative totals
• /cache export — writes the same stats data to session-name.csv at the project root

Commands

/cache graph

Opens a TUI overlay with three switchable views:

Key	View	Description
1	Per-turn (%)	Cache hit % per individual turn (default)
2	Cumulative (%)	Running cache hit % across all turns so far
3	Cumulative (total)	Running cumulative token volumes (input / cacheWrite / cacheRead)

Keyboard shortcuts inside the dialog:

• 1 / 2 / 3 — jump directly to that view
• v — cycle view forward
• V (Shift+v) — cycle view backward
• ↑/↓, PgUp/PgDn, Home/End — scroll
• q / Esc — close

All views show active-branch totals and whole-tree totals at the top.

Cache hit % is computed as:

cacheRead / (input + cacheRead + cacheWrite)

The denominator is the full prompt size that was sent in the turn:

• input — fresh, non-cached prompt tokens
• cacheRead — prompt tokens served from cache
• cacheWrite — prompt tokens that were freshly written to cache this turn (Anthropic-style providers report this separately from input; OpenAI-style providers report cacheWrite = 0, so the formula behaves identically there)

The cumulative-total chart uses distinct glyphs per series (▇ input, ░ cacheWrite, ▒ cacheRead) with a dynamic scale shown in the legend (default: 1 row = 5,000 tokens).

/cache stats

Opens a TUI overlay table that shows:

• one row per assistant message with usage data
• whether the message is on the current active branch
• prompt / received / cache-hit / cache-write tokens
• per-message cache hit %
• cumulative totals for the active branch and the whole tree

/cache export

Writes a CSV to the project root:

• filename: session-name.csv
• uses the current pi session name when available
• falls back to the session file basename if the session has no explicit name
• contains summary rows plus the per-message rows shown in /cache stats
• can be opened in Excel to build graphs from the exported columns

Install from npm

Install globally via pi:

pi install pi-cache-graph

Or add it to your pi settings manually in .pi/settings.json:

{
  "packages": [
    "pi-cache-graph"
  ]
}

Once installed, the /cache commands are available in any pi session.

Install from local source (development)

Clone the repo and run pi with this extension directly:

git clone https://github.com/championswimmer/pi-cache-graph.git
cd pi-cache-graph
npm install
pi -e .

Or install the local path into pi:

pi install /path/to/pi-cache-graph

Or add it to .pi/settings.json:

{
  "packages": [
    "/path/to/pi-cache-graph"
  ]
}

Development

npm install
npm run check

Maintainer release workflow

This repo includes a project-local Pi release workflow for maintainers:

• prompt template: /release <major|minor|patch>
• skill: .agents/skills/release/SKILL.md
• helper script: scripts/release.mjs
• detailed notes: docs/releasing.md

The release flow bumps the version, creates the release tag, pushes main plus the tag, and then relies on .github/workflows/publish.yml to publish to npm.

Files

• index.ts — extension entrypoint
• src/index.ts — command registration
• src/session-data.ts — session traversal and metric computation
• src/cumulative.ts — cumulative series computation (pure, no UI dependency)
• src/cache-math.ts — cache hit % and totals calculations
• src/format-utils.ts — number/percent formatting helpers
• src/graph-view.ts — graph rendering
• src/stats-view.ts — stats table rendering
• src/scroll-dialog.ts — scrollable TUI overlay component
• src/render-utils.ts — shared rendering helpers
• src/export.ts — CSV export logic
• src/types.ts — shared TypeScript interfaces