# pi-cache-insight

Cache-prefix break analysis for the [pi coding agent](https://pi.dev/).

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