$ cat ~/map/pi-cache-lens.md

pi-cache-lens

Status-bar chip tracking per-request and session KV cache hit rates, with background forensics attributing every drop.

extensions✓ Oct 31

pi install git:github.com/w31r4/pi-cache-lens, then update anytime with pi update. The chip renders through the built-in pi footer automatically; pi-powerline-footer and pi-cc-extensions have documented integration snippets in the README.

## TL;DR

A zero-overhead pi extension that displays prefix KV cache hit rates for the latest request and the whole session in the status bar, and runs background forensics that attribute every cache drop — cold start, mutated tools, rewritten history, TTL expiry, model change, or gateway drift — using hashes and offsets only, never raw prompt text.

## Key points

• $Dual hit-rate chip: the latest request and the cumulative session, colored accent at 70% or above, warning between 30% and 69%, error below 30%, with a muted warmup across a session's first three calls.
• $Zero overhead by construction: no tool schemas are registered and outgoing requests are never mutated; the extension observes traffic in the before_provider_request hook.
• $Root-cause tags separate miss families: cold start, below-minimum tokens, mutated tools, provider strict-tool fallback, mutated system prompt, rewritten or compacted history, TTL expiry, model change, gateway routing drift, and sharp partial drops without comparable evidence.
• $Credential-safe attribution: the normalized system prompt, tools including inline additional_tools, provider effort markers, and conversation items are fingerprinted, and storage holds hashes, byte lengths, and char@/byte@ offsets — never prompt excerpts.
• $Slash commands: /cache shows the session summary and the last eight calls with short hashes, /cache anomalies the ten most recent drops across sessions, and /cache path prints the forensics file locations.
• $Forensics live under ~/.pi/agent/cache-lens/: latest-report.md grouped by model, events.jsonl rotating at 10 MB, and anomalies.jsonl holding demonstrated drops only.
• $TTL thresholds follow the provider: 290 seconds by default when cache_control or prompt_cache_key is active, 1800 for a 30-minute prompt cache TTL, up to 86400 for 24 hours; every threshold is configurable in ~/.pi/agent/cache-lens.json.
• $The UI locale auto-detects from rpiv-i18n or LANG (zh or en) and can be forced in the config file.

## FAQ

## References

• README (root-cause tags, install, integration, configuration) ↗

Last updated: Oct 30, 2026