pi-stats-insight

Observability extension for pi: cache hit rate, tool stats, and provider errors — data pi doesn't show in its built-in footer.

Footer

Adds a compact status line via ctx.ui.setStatus (does NOT replace pi's native footer):

⚡ cache 80%  🔧 12 tools  ⏱ 0.8s avg  ❌ 2 err

Indicator	Meaning	When shown
⚡/🔋/⚠️ cache	Cache hit rate	≥80% ⚡, ≥50% 🔋, <50% ⚠️. Hidden if provider doesn't support caching
🔧 tools	Tool call count this session	When >0
⏱ avg	Average tool response time	When >0
❌ err	Provider error count (HTTP 4xx/5xx)	When >0

No overlap with pi's built-in footer — pi already shows token/context usage; we show what it doesn't.

/stats command

Interactive drill-down via ctx.ui.select:

• Tokens & Cost — input/output/cacheRead/cacheWrite breakdown + total cost
• Cache Performance — hit rate per provider
• Tools — per-tool call count, errors, avg duration, result size
• Context & Compaction — context window usage + compaction history
• Latency & Errors — HTTP error details

/stats reset — clear session stats.

Cache hit rate formula

hitRate = cacheRead / (cacheRead + input + cacheWrite)

Works across providers because pi normalizes cache metrics:

Provider	cacheRead source	cacheWrite	input
Anthropic	cache_read_input_tokens	cache_creation_input_tokens	input_tokens
OpenAI	cached_tokens	0	input_tokens - cached_tokens
Google	cachedContentTokenCount	0	promptTokenCount - cached
Mistral	0 (not exposed)	0	all tokens
Custom/GLM	0	0	all tokens

Persistence

Session stats are saved to ~/.pi/agent/pi-stats-insight/<session-id>.jsonl (append-only).

Install

pi install npm:pi-stats-insight

Or add to ~/.pi/agent/settings.json packages array:

{ "packages": ["npm:pi-stats-insight"] }

Config

No configuration needed. Zero-intrusion — hooks only, no pi file modifications.

License

MIT