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](README.zh.md) · LLM index: [llms.txt](llms.txt) · Agent guide: [AGENTS.md](AGENTS.md)

!dsh-plugin !DeepSeek Harness !license !install

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

---

📑 Table of Contents

• [✨ Features](#-features)
• [🏗️ How it works](#️-how-it-works)
• [🚀 Quick start](#-quick-start)
• [⚙️ Configuration](#️-configuration)
• [❓ FAQ](#-faq)
• [⚠️ Security notes](#️-security-notes)
• [📦 Project structure](#-project-structure)
• [🙏 Credits](#-credits)

---

✨ Features

🏗️ 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

# or directly from GitHub (any DSH machine):
dsh plugin --profile web add git+https://github.com/Zenjibad/headroom-stats-plugin.git

dsh plugin add is a pnpm add into the profile plus a dsh.profile.bundles reconcile: seeing this package's dsh.bundle declaration, it appends headroom-stats-plugin to the bundle stack. Restart DSH (or hard-refresh). On boot the client-modules scanner resolves exports["./client"] and the settings page + dock line appear. No per-session define, survives restarts.

Manual profile mount (alternative)

1. git clone https://github.com/Zenjibad/headroom-stats-plugin.git (any location). 2. Add to ~/.dsh/profiles/web/package.json dependencies: "headroom-stats-plugin": "link:<repo-path>", then pnpm install in the profile dir. 3. Restart DSH.

> If a previous dynamic install of this plugin is running, stop it first (cordis_stop) to avoid double-mounting the two settings seats.

Requirements

• Headroom proxy running on this machine (writing ~/.headroom/proxy_savings.json, or the file HEADROOM_SAVINGS_PATH points at).
• Missing file → settings page shows "unavailable + error", stats line hides — no crash, no noise.

⚙️ Configuration

No config file, no persisted settings. The path is resolved dynamically from these env vars (probed once, cached):

Poll interval: 5s constant (POLL_MS in src/client/index.tsx).

❓ FAQ

Q: Settings page shows "Headroom stats unavailable"? A: proxy_savings.json not found. Confirm the headroom proxy is running and the file exists; check the env-var paths.

Q: The composer stats line is missing? A: Deliberate — the line renders nothing when data is absent (no noise). It reappears ≤5s after data returns.

Q: Why do numbers differ from what I saw before? A: proxy_savings.json grows continuously as the proxy compresses; stats are live values. The fixture in tests/fixtures/ is a point-in-time snapshot — staleness is by design.

Q: My old dynamic plugin is still showing two dashboards after installing this? A: Stop/remove the dynamic one (cordis_stop / cordis_undefine) — it re-defines the same seats.

Q: How do I remove it? A: dsh plugin --profile web rm headroom-stats-plugin (or delete the profile dependency + bundle entry) and restart DSH.

⚠️ Security notes

• The plugin only reads the headroom data file — no writes, no network (the subprocess call is one-time and only echoes env vars).
• Path detection honors headroom's official env vars; it never guesses or scans the disk.
• Dollar figures are headroom's model-priced "cost avoided" estimates, not real bills.

📦 Project structure

headroom-stats-plugin/
├── src/
│   ├── index.ts            # host half: env probe, fs read, reshape, /headroom-stats/api route
│   └── client/index.tsx    # client bundle: 5s poller, dashboard, dock line
├── cordis.patch.yml        # dsh.bundle patch (inserts the plugin row on boot)
├── tsdown.config.ts        # bundles host (node ESM) + client (CJS ModuleLoader)
├── package.json            # name, exports["./client"], dsh.client + dsh.bundle
├── lib/                    # build output (index.js, client.js)
├── tests/fixtures/         # real-shape snapshot of proxy_savings.json
├── AGENTS.md               # repository guide for AI agents
├── llms.txt / llms-full.txt
├── README.md / README.zh.md
└── LICENSE

🙏 Credits

• Headroom — the compression proxy and proxy_savings.json data source.
• DeepSeek Harness — the DSH plugin/dynamic runtime, Slots, theme, webServer, client-modules.
• DSH-better-sidebar — reference for the packaged client-plugin build pattern.

📄 License

[MIT](LICENSE)