{"id":45769,"library":"pi-cache-graph","title":"pi-cache-graph","description":"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.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/championswimmer/pi-cache-graph","tags":["javascript","pi-package","pi-extension","cache","tui"],"install":[{"cmd":"npm install pi-cache-graph","lang":"bash","label":"npm"},{"cmd":"yarn add pi-cache-graph","lang":"bash","label":"yarn"},{"cmd":"pnpm add pi-cache-graph","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: provides pi AI core capabilities","package":"@mariozechner/pi-ai","optional":false},{"reason":"Peer dependency: coding agent integration for pi","package":"@mariozechner/pi-coding-agent","optional":false},{"reason":"Peer dependency: terminal UI framework for overlays","package":"@mariozechner/pi-tui","optional":false}],"imports":[{"note":"Package is ESM-only; no default export. Activation is handled by pi extension system.","wrong":"const piCacheGraph = require('pi-cache-graph');","symbol":"default export","correct":"import { activate } from 'pi-cache-graph';"},{"note":"Types are exported as type-only; use import type for correct tree-shaking.","wrong":"import { CacheStats } from 'pi-cache-graph';","symbol":"type definitions","correct":"import type { CacheStats, CacheGraphView } from 'pi-cache-graph';"},{"note":"Commands are not exported as functions; they are activated via pi's command system.","wrong":"import { cacheGraph, cacheStats } from 'pi-cache-graph';","symbol":"commands","correct":"/* Commands are registered via pi extension interface, not imported directly */"}],"quickstart":{"code":"// Install the extension globally via pi\npi install pi-cache-graph\n\n// After installation, start a pi session and use /cache commands:\npi\n> /cache graph    # Opens TUI overlay with cache hit graphs\n> /cache stats    # Shows per-message token breakdown\n> /cache export   # Exports data to CSV\n\n// Or add to .pi/settings.json:\n{\n  \"packages\": [\"pi-cache-graph\"]\n}\n\n// For developers: clone and test locally\ngit clone https://github.com/championswimmer/pi-cache-graph.git\ncd pi-cache-graph\nnpm install\npi -e .","lang":"typescript","description":"Installation and basic usage of pi-cache-graph extension within pi session."},"warnings":[{"fix":"Update pi to latest version","message":"Requires pi 1.0 or later; not compatible with pi 0.x","severity":"breaking","affected_versions":"<0.1.0"},{"fix":"Check for updated configuration options in next release","message":"The /cache export command writes CSV to project root; future versions may change output path","severity":"deprecated","affected_versions":"0.2.0"},{"fix":"Understand the denominator includes all prompt token types","message":"Cache hit % formula uses (cacheRead / (input + cacheRead + cacheWrite)) which differs from some naive interpretations (cacheRead / totalPrompt)","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"No action needed; formula remains consistent across providers","message":"OpenAI-style providers report cacheWrite = 0; cache hit % may appear lower than expected","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Resize terminal or use a terminal emulator with full TUI support","message":"TUI overlays require a terminal with sufficient rows/columns; may not render correctly in minimal terminals","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'/cache':15,17,19 '0.2.0':38 'across':35 'adapt':79 'anthrop':82 'base':11 'cach':3,12,29,76,95 'command':14 'companion':45 'context':28,49 'csv':66 'cumul':58,59 'design':42 'differenti':68 'export':20,67 'extens':7,94 'formula':78 'graph':4,16,53 'hit':30,77 'inspect':13 'integr':72 'javascript':88 'llm':27 'messag':63 'monitor':25 'nativ':70 'need':41 'observ':44 'offer':51 'openai':85 'openai-styl':84 'overlay':74 'packag':91 'per':56,62 'per-messag':61 'per-turn':55 'pi':2,6,48,71,90,93 'pi-cache-graph':1 'pi-context-prun':47 'pi-extens':92 'pi-packag':89 'provid':8,87 'prune':50 'rate':31 'real':23 'real-tim':22 'releas':39 'session':36 'stat':18,64 'style':86 'three':52 'time':24 'token':33 'tui':10,73,96 'tui-bas':9 'turn':57 'usag':34 'version':37 'view':54 'volum':60","created_at":"2026-06-07T12:56:38.027330+00:00","updated_at":"2026-06-07T12:56:38.027330+00:00","problems":[{"fix":"Run 'pi install pi-cache-graph' or add package to settings.json","cause":"Extension not installed globally or not added to .pi/settings.json","error":"Error: Cannot find module 'pi-cache-graph'"},{"fix":"Update pi and ensure extension is listed in packages","cause":"pi version <1.0 or extension not activated","error":"pi: command not found: /cache graph"},{"fix":"Update pi to 1.0+","cause":"Using older pi version that doesn't support extension commands","error":"TypeError: Cannot read properties of undefined (reading 'graph')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/championswimmer/pi-cache-graph#readme","github":"https://github.com/championswimmer/pi-cache-graph","docs":null,"changelog":null,"pypi":null,"npm":"pi-cache-graph","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}