dsh-usage-plugin
A native sidebar usage panel for DeepSeek Harness Web: shows your official DeepSeek balance and token usage history (today / last 7 days) right in the sidebar, with no separate process and no cross-origin calls.
A trigger button appears at the bottom of the left sidebar, above Settings — full-width with a label when the sidebar is expanded, a compact icon when collapsed. Click it to open the panel: live balance, today's input / output / cache tokens, and a 7-day trend computed from your own session logs.
Features
- Official balance — live query of
api.deepseek.com/user/balance using the API key DSH already has (DEEPSEEK_API_KEY from your credentials), never stored in the browser.
- Token usage history — reads your
$DSH_HOME/sessions logs and aggregates input / output / cache tokens per day (today, totals, daily average, cache hit rate).
- Sidebar integration — registers a
sidebar.footer.action trigger and a shell.overlay modal; layout follows the DSH design tokens (light/dark themes included).
- Zero footprint — no daemon, no config, no database; data comes from the same DSH installation you already run.
Requirements
| Requirement | Version |
|---|
| DeepSeek Harness | >= 0.1.0-rc.7 (verified on 0.1.5-rc.2) |
| Node.js | >= 20 |
| pnpm | >= 10 (for dsh plugin installation) |
| API key | an existing DEEPSEEK_API_KEY credential (the one DSH already uses) |
Installation
From anywhere, run:
dsh plugin --profile web add dsh-usage-plugin
That's it — the package declares a dsh.bundle patch, so dsh plugin automatically mounts it into the profile layer stack. Then:
- Restart
dsh web (stop and start the process). The loader tree is composed once at boot, so a plugin installed into a running server is not picked up until then.
- Hard refresh the browser (
Cmd/Ctrl+Shift+R).
- Look for the usage icon at the bottom of the left sidebar.
Verifying the install
GET /api/dsh-usage/balance and GET /api/dsh-usage/stats?days=N sit behind the same process-token fence as the rest of DSH's /api (dsh >= 0.1.5), so a bare curl gets 401 unauthorized. Use the browser page, or pass the token that dsh web prints at startup:
# dsh web: http://127.0.0.1:3080/?token=XXXXXXXX
node scripts/verify-install.mjs 3080 XXXXXXXX
The verifier ships with the package, so an npm install can run it from ~/.dsh/profiles/web/node_modules/dsh-usage-plugin.
Alternatives
- From GitHub:
dsh plugin --profile web add github:lurejewel/dsh-usage-plugin
- From a release tarball:
dsh plugin --profile web add https://github.com/lurejewel/dsh-usage-plugin/archive/refs/tags/v0.1.3.tar.gz
- From a local checkout (development): run the same command from inside this repo. Quote the path:
dsh plugin forwards its arguments to pnpm through a shell without quoting them, so an unquoted path containing spaces is split into several package specs — D:\Software\DeepSeek Harness\dsh-usage-plugin becomes link:D:/Software/DeepSeek plus a phantom Harness\dsh-usage-plugin dependency, and the plugin is dropped from dsh.profile.bundles:
dsh plugin --profile web add '"D:\Software\DeepSeek Harness\dsh-usage-plugin"'
scripts/install-local.ps1 does exactly this.
- Manual mount on older setups: add the row below to
~/.dsh/profiles/web/cordis.patch.yml, then restart:
- insert:
- id: dsh-usage-plugin
name: dsh-usage-plugin
Uninstall
dsh plugin --profile web remove dsh-usage-plugin
Then restart dsh web.
How it works
One package, two halves, mounted as a normal Cordis plugin:
lib/index.js Host half: same-origin HTTP routes on the DSH web server
lib/client.js Browser half: __ModuleLoader__ bundle served to the web GUI
lib/usage-history.js Session-log reader (zstd frame scan + per-step dedup + daily aggregation)
GET /api/dsh-usage/balance — live official balance (server-side call, key never leaves the server).GET /api/dsh-usage/stats?days=N — balance + usage history; N defaults to 7, clamped to 1–90.
Implementation notes worth knowing:
- DSH session logs (
session.<generation>.jsonl.zstd) are multiple concatenated zstd frames (one frame per persistence batch); the reader scans frame-by-frame instead of assuming a single frame. One damaged frame costs only its own rows.
- Session artifacts are versioned format generations —
session.jsonl.zstd is the released v0 root, session.vN.jsonl.zstd a later one, and DSH always writes and reads the highest generation present in a session directory. The reader therefore selects the highest canonical generation per session (never the plain v0 file alone, and never more than one file per session): a lower generation stops at that session's migration point, while reading two of them would double-count.
assistant/message and assistant/chunk events report the same usage numbers for the same (turn, step); the reader de-duplicates by (turn, step) so totals are not double-counted.- The API key is resolved through DSH's
credentials service — the same source the DeepSeek provider uses. Nothing is stored in the browser; all calls are same-origin.
- Both routes inherit DSH's browser-trust fence, and on dsh >= 0.1.5 the client bundle is delivered as part of the shell's single combined
/plugins/??… request rather than per-package URLs. Neither changes the browser half: it runs inside the authenticated page.
Privacy & security
- The balance call goes from your server to
api.deepseek.com; the API key never enters the browser.
- The panel only reads your own session logs under
$DSH_HOME/sessions.
- No telemetry, no third-party network calls.
Development
npm test # unit tests (frame scan / decode / dedup / 30-day window)
npm run test:client-boot # boot the real client bundle in Node against mock slots
npm run test:standalone # in-process E2E: real cordis + real API + real logs
# (needs a local DSH install with @deepseek-ai packages
# reachable at $DSH_HOME/profiles/node_modules, a
# DEEPSEEK_API_KEY credential, and session logs)
npm run verify -- 3080 <token> # post-restart check against a running dsh web
lib/ is the shipped artifact and doubles as readable source (plain ESM, documented).
Windows helper scripts (optional)
scripts/install-local.ps1 — one-click local install as a link: to this repo (quotes the path for the dsh plugin shell hop).scripts/restart-web.ps1 — restart dsh web, read the tokenized URL from the server log, then run the verification.scripts/verify-install.mjs — post-restart check: token exchange, stats/balance routes, materialized client row, combined bundle contents. On dsh >= 0.1.5 it needs <port> <token>.
The two .ps1 helpers live in the git checkout only; verify-install.mjs is published in the npm package as well.
License
MIT
