pi-cache-graph

library0.2.0jsnpmunverified

A pi extension providing TUI-based cache inspection commands (/cache graph, /cache stats, /cache export) for real-time monitoring of LLM context cache hit rates and token usage across sessions. Version 0.2.0, released as needed. Designed as observability companion for pi-context-prune, offering three graph views (per-turn %, cumulative %, cumulative volumes), per-message stats, and CSV export. Differentiates with native pi integration, TUI overlays, and cache hit formula adaptable to both Anthropic and OpenAI-style providers.

devops

npm install pi-cache-graph

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PI-CACHE-GRAPH

pi-cache-graph

devopsjavascriptv0.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export

✓ import { activate } from 'pi-cache-graph';

✗ const piCacheGraph = require('pi-cache-graph');

Package is ESM-only; no default export. Activation is handled by pi extension system.

type definitions

✓ import type { CacheStats, CacheGraphView } from 'pi-cache-graph';

✗ import { CacheStats } from 'pi-cache-graph';

Types are exported as type-only; use import type for correct tree-shaking.

commands

✓ /* Commands are registered via pi extension interface, not imported directly */

✗ import { cacheGraph, cacheStats } from 'pi-cache-graph';

Commands are not exported as functions; they are activated via pi's command system.

Installation and basic usage of pi-cache-graph extension within pi session.

// Install the extension globally via pi pi install pi-cache-graph // After installation, start a pi session and use /cache commands: pi > /cache graph # Opens TUI overlay with cache hit graphs > /cache stats # Shows per-message token breakdown > /cache export # Exports data to CSV // Or add to .pi/settings.json: { "packages": ["pi-cache-graph"] } // For developers: clone and test locally git clone https://github.com/championswimmer/pi-cache-graph.git cd pi-cache-graph npm install pi -e .

Debug

Known issues

breakingRequires pi 1.0 or later; not compatible with pi 0.x

fix

Update pi to latest version

affects: <0.1.0

deprecatedThe /cache export command writes CSV to project root; future versions may change output path

fix

Check for updated configuration options in next release

affects: 0.2.0

gotchaCache hit % formula uses (cacheRead / (input + cacheRead + cacheWrite)) which differs from some naive interpretations (cacheRead / totalPrompt)

fix

Understand the denominator includes all prompt token types

affects: >=0.1.0

gotchaOpenAI-style providers report cacheWrite = 0; cache hit % may appear lower than expected

fix

No action needed; formula remains consistent across providers

affects: >=0.1.0

gotchaTUI overlays require a terminal with sufficient rows/columns; may not render correctly in minimal terminals

fix

Resize terminal or use a terminal emulator with full TUI support

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'pi-cache-graph'

Extension not installed globally or not added to .pi/settings.json

fix

Run 'pi install pi-cache-graph' or add package to settings.json

pi: command not found: /cache graph

pi version <1.0 or extension not activated

fix

Update pi and ensure extension is listed in packages

TypeError: Cannot read properties of undefined (reading 'graph')

Using older pi version that doesn't support extension commands

fix

Update pi to 1.0+

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

@mariozechner/pi-airequiredPeer dependency: provides pi AI core capabilities

@mariozechner/pi-coding-agentrequiredPeer dependency: coding agent integration for pi

@mariozechner/pi-tuirequiredPeer dependency: terminal UI framework for overlays

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/championswimmer/pi-cache-graph ↗

packagepi-cache-graph ↗

homepagehttps://github.com/championswimmer/pi-cache-graph#readme ↗