pi-cache-insight

Cache-prefix break analysis for the pi coding agent.

Pi's request context is a three-part prefix — system prompt + tool definitions

• messages — and providers cache it as a prefix. New information (searches, file reads, conversation) is always appended at the end, so the prefix stays cacheable. A cache is only truly broken when something rewrites the prefix: a tool-set change, a context-file edit, an extension injection.

This extension detects exactly that signal and nothing else.

Features

• /cache — a panel rendered in the editor slot (same mechanism as /model), with three views:
  • Session summary — active-branch vs whole-tree totals, context-window occupancy, hit-rate tier coloring (≥95% green / 80–95% yellow / <80% red), delta row when the session tree has side branches
  • Turn distribution — horizontal log-scale bar chart of turns per hit-rate bucket (0–50 / 50–80 / 80–90 / 90–95 / 95–98 / >98)
  • Miss analysis — every turn where the cacheable prefix was broken, judged by the miss ratio against the cached prefix length (10% × √(100k / prefix) threshold, clamped 2–30%), with the likely cause (model switch / thinking change / after compact / prefix shrank / context rebuilt / idle gap; tags co-occur — a restart creates both an idle gap and a rebuilt prefix, and the stronger signal is never hidden), the estimated extra cost of each miss, session waste total, and cache leverage. Idle expiry uses the TTL applicable to the model's protocol (5 min explicit for anthropic-messages, 10 min heuristic for implicit prefix caches); /cache export writes the cause tags into each row's notes column
• /cache export — writes the same stats as CSV to the OS temp dir (never litters your project)

Install

pi install npm:pi-cache-insight

Then /reload.

Usage

| Key | Action | |---|---| | Tab | cycle views | | j / k | scroll | | q | close |

Why not a hit-rate threshold?

In a long session the hit rate stays high (95%+) even when the prefix is broken — 5% of a 500k prefix is as significant as 10% of a 100k prefix. The miss ratio (re-billed prefix tokens ÷ previous prompt) is the only meaningful indicator, so it scales with the cached length. Appended information never triggers it.

Commands

• /cache — open the panel (defaults to the per-message table)
• /cache graph — open on the turn-distribution chart
• /cache export — export stats CSV to the OS temp dir