@mrclrchtr/supi-cache

SuPi Cache — prompt cache health monitoring and cross-session forensics

Packages

Package details

extension

Install @mrclrchtr/supi-cache from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@mrclrchtr/supi-cache

Package: @mrclrchtr/supi-cache
Version: 1.14.0
Published: Jun 18, 2026
Downloads: 2,586/mo · 379/wk
Author: mrclrchtr
License: MIT
Types: extension
Size: 148 KB
Dependencies: 1 dependency · 4 peers

Pi manifest JSON

{
  "extensions": [
    "./src/extension.ts"
  ],
  "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-cache/assets/logo.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@mrclrchtr/supi-cache

Adds prompt-cache monitoring and cache-regression forensics to the pi coding agent.

Install

pi install npm:@mrclrchtr/supi-cache

This is a beta package. Install individually.

For local development:

pi install ./packages/supi-cache

What you get

After install, the package does two things:

Monitor the current session
- records per-turn cache usage from assistant messages
- updates a footer status for cache health
- warns when the cache hit rate drops enough to count as a regression
- tries to explain the drop as compaction, model change, prompt change, or unknown
Investigate past sessions
- scans session files for cache regressions across time
- groups findings into a few built-in query patterns
- keeps agent-facing results redacted to structural fingerprints instead of raw command text or file paths

Cache history report

Commands and tool

`/supi-cache-history`

Shows cache history for the current session.

The report includes per-turn values for:

input tokens
cache read tokens
cache write tokens
hit rate
notes about detected regressions

`/supi-cache-forensics`

Runs a cross-session investigation.

Supported patterns:

breakdown — count regressions by cause
hotspots — show the largest drops
correlate — show which preceding tool calls correlate with drops
idle — show drops after long gaps between turns

Useful flags:

--since 7d
--pattern breakdown
--min-drop 20

Cache forensics report

`supi_cache_forensics`

Adds one model-callable tool with the same four patterns: hotspots, breakdown, correlate, and idle.

The tool returns JSON text. Before results are returned to the model, human-only details such as _pathsInvolved and _commandSummaries are stripped out.

Settings

This package registers a Cache section in /supi-settings.

Available settings:

enabled — turn monitoring on or off
notifications — show warning notifications for regressions
regressionThreshold — percentage-point drop that counts as a regression warning
idleThresholdMinutes — inactivity gap used to classify idle-time regressions

Defaults:

{
  "supi-cache": {
    "enabled": true,
    "notifications": true,
    "regressionThreshold": 25,
    "idleThresholdMinutes": 5
  }
}

The config loader also reads the legacy cache-monitor section for upgrades, but supi-cache is the current config section.

Source

src/monitor/monitor.ts — live monitoring, commands, and tool registration
src/forensics/forensics.ts — cross-session scan pipeline
src/report/history.ts — current-session history report
src/report/forensics.ts — cross-session forensics report