headroom-stats-plugin

If you are already running the Headroom compression proxy to cut token costs in DeepSeek Harness, you know the small daily friction: the savings data sits quietly in a JSON file while the DSH interface shows you nothing. headroom-stats-plugin bridges that gap by pulling the numbers into the places where you actually look. The Settings page hosts a full dashboard with lifetime KPIs—tokens saved, compression savings, cache savings, total requests—plus a top-10 project breakdown table. Under the chat input, a compact stats line updates every five seconds so you can glance at current-session savings without leaving the composer.

The plugin follows a strict pull-only, read-only model: it reads proxy_savings.json every five seconds, never writes to the Headroom directory, makes no network calls, and uses no file watchers. When the data file is missing or unparseable, the stats line simply hides itself rather than throwing errors, and recovers automatically the moment data returns. Path resolution honors HEADROOM_SAVINGS_PATH, HEADROOM_WORKSPACE_DIR, and the user-profile fallback, so it adapts to different machine layouts without hardcoding. All colors are driven by DSW design tokens, following light and dark themes automatically. Once installed as a profile plugin, it persists across restarts and needs no per-session definition.

It is built for developers who work at the intersection of DSH and the Headroom proxy and want at-a-glance visibility into token and cost savings—no terminal digging, no separate browser tab, just open Settings or glance below the input field.