headroom-stats-plugin · Live Headroom Savings Dashboard for DeepSeek Harness (DSH)

Show real-time token/cost savings from the Headroom compression proxy inside the DeepSeek Harness (DSH) Web UI: a full dashboard in Settings plus a persistent stats line under the composer. 在 DSH 内实时展示 Headroom 压节省统计：设置页仪表盘 + 输入区常驻统计行。

中文文档: README.zh.md · LLM index: llms.txt · Agent guide: AGENTS.md

Keywords: dsh-plugin · deepseek-harness-plugin · headroom · token-savings · compression · tokens · cost · stats · dashboard

---

📑 Table of Contents

• ✨ Features
• 🏗️ How it works
• 🚀 Quick start
• ⚙️ Configuration
• ❓ FAQ
• ⚠️ Security notes
• 📦 Project structure
• 🙏 Credits

---

✨ Features

Feature	Description
📊 Settings dashboard	Settings → Headroom Stats: lifetime KPIs (tokens saved, compression $, cache $, requests), current-session card, cache-vs-compression split bar, top-10 projects table, loading/error/stale states
🪧 Composer stats line	One line under the chat input: Headroom: 11.4M tokens saved · $26.23 · 11.2% this session, refreshed every 5s
🧭 Dynamic path detection	No hardcoded paths — shareable across machines: probes HEADROOM_SAVINGS_PATH → HEADROOM_WORKSPACE_DIR → %USERPROFILE%\.headroom
⚡ 5s live refresh	One shared poller feeds both seats from a single snapshot — no duplicate file reads
🌗 Theme-aware	All colors use --dsw-alias-* design tokens; follows light/dark automatically
♨️ Survives restarts	Real profile-bundled plugin: install once with dsh plugin add, auto-loads on every DSH boot — no per-session define, no cordis_define

🏗️ How it works

Headroom proxy ──writes──> ~/.headroom/proxy_savings.json (grows continuously)
                                 │
Host half (DSH process)          ▼
  └─ one-time env probe: cmd /c echo %HEADROOM_SAVINGS_PATH%&echo %HEADROOM_WORKSPACE_DIR%&echo %USERPROFILE%
       (DSH host sandbox exposes no direct env access; fetched via subprocess)
  └─ fs service stat/readText → snake_case→camelCase reshape
  └─ webServer route GET /headroom-stats/api → JSON snapshot
                                 │
Client bundle (browser)          ▼
  └─ single 5s poller → fetch(/headroom-stats/api) → snapshot fan-out to two seats
       ├─ settings.section (id headroom-stats)       → full dashboard
       └─ conversation.composer.dock (id headroom-dock) → stats line

• Pure pull model: no push, no events, no file watching; missing/unparseable file → {ok:false,error}, UI shows unavailable, polling self-recovers.
• Read-only: the plugin never writes to the headroom directory.
• Persistence: ships dsh.bundle (cordis.patch.yml) + dsh.client (exports["./client"], bundled) so it installs as a real profile plugin that the DSH client-modules scanner loads on every boot.

🚀 Quick start

Standard install: dsh plugin add (persists across restarts)

Install the package from this GitHub repo (or from npm once published):

# local directory (from the parent of this repo):
dsh plugin --profile web add ./headroom-stats-plugin

…