# headroom-stats-plugin

> Live token/cost-savings dashboard for 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 压节省统计：设置页仪表盘 + 输入区常驻统计行。

For the complete combined document, see [llms-full.txt](llms-full.txt). For human-readable docs, see [README.md](README.md) (English) and [README.zh.md](README.zh.md) (中文).

## Key facts

- [Repository](https://github.com/Zenjibad/headroom-stats-plugin): public GitHub repo, MIT license, `dsh-plugin` topic.
- [Install](README.md#-quick-start): packaged profile plugin — `dsh plugin --profile web add <spec>` (local dir or `git+https://github.com/Zenjibad/headroom-stats-plugin.git`), then restart DSH. `dsh.bundle` (`cordis.patch.yml`) mounts the host half; `dsh.client` + `exports["./client"]` register the browser half. Survives restarts, no cordis_define.
- [Data source](README.md#️-how-it-works): host reads `~/.headroom/proxy_savings.json` (env-overridable via `HEADROOM_SAVINGS_PATH` / `HEADROOM_WORKSPACE_DIR`) — read-only, and serves the reshaped snapshot over `GET /headroom-stats/api` (webServer route).
- [UI seats](README.md#-features): `settings.section` id `headroom-stats` (dashboard: lifetime KPIs, session, cache-vs-compression split, top-10 projects) + `conversation.composer.dock` id `headroom-dock` (one-line summary), fed by one shared 5s poller fetching the host route.
- [Path detection](README.md#️-configuration): dynamic — `HEADROOM_SAVINGS_PATH` → `HEADROOM_WORKSPACE_DIR`/`proxy_savings.json` → `%USERPROFILE%\.headroom\proxy_savings.json`; env read once via the `subprocess` service (DSH host sandbox has no env access).
- [Failure mode](README.md#-faq): missing/unparseable file → `{ok:false,error}`; settings shows unavailable, dock line hides, polling self-recovers ≤5s.

## Documentation

- [README.md (English)](README.md): features, architecture, quick start, config, FAQ, security notes.
- [README.zh.md (中文)](README.zh.md): same content in Chinese.
- [src/index.ts](src/index.ts): host half — env probe, fs read, reshape, `/headroom-stats/api` route.
- [src/client/index.tsx](src/client/index.tsx): client bundle — 5s poller, dashboard, dock line.
- [AGENTS.md](AGENTS.md): repository guide for AI agents (layout, key behaviors, probed environment facts, testing).
- [package.json](package.json): npm metadata with `dsh.bundle` + `dsh.client` manifests for `dsh plugin add`.

## Source layout

- [src/index.ts](src/index.ts): the host half — dynamic path detection, `fs` read + reshape, `webServer` JSON route.
- [src/client/index.tsx](src/client/index.tsx): the client bundle — single 5s poller, `React.createElement` dashboard, dock line, `<style data-plugin>` with `--dsw-alias-*` theming.
- [cordis.patch.yml](cordis.patch.yml): `dsh.bundle` patch inserting the plugin row.
- [tsdown.config.ts](tsdown.config.ts): builds host (node ESM) + client (CJS ModuleLoader closure).
- [tests/fixtures/proxy_savings.json](tests/fixtures/proxy_savings.json): real-shape snapshot of the data file (point-in-time; the live file grows continuously).