dsh-stats-hud — live session stats reimagined as a sci-fi HUD
dsh-stats-hud
A sci-fi HUD for DeepSeek Harness: the session's stats become game-style level bars in a vertical column fixed to the far right edge of the web UI — without touching the original stats line.
screenshot
Changelog
2026-09-11 — Verified against DSH 0.1.5-rc.1 (no code changes needed)
- Re-audited every interface the HUD touches against
dsh 0.1.5-rc.1 (client packages 0.1.5-rc.2): conversation.composer.dock is still declared by the composer bar and still renders declaration-gated, so the ctx.slots.inject(...) registration stays as-is; the dock's id/order/label options, the useSession / useProjection standard props (plus two new ones, useResource / usePanelInfo), all four projections (sessionStats, tokenUsage, contextPressure, contextBreakdown) and the [data-composer-card] / data-slot DOM markers are unchanged.
- Manifest contract unchanged (
dsh.bundle.patch, dsh.client.platform, window.__ModuleLoader__.load({id, factory})); dsh plugin is still a pnpm forwarder. Removed a dead dsh.client.inject entry: @deepseek-ai/dsh-client-runtime no longer exists in the tree (unknown names are ignored harmlessly). Package version bumped to 0.1.1.
- Docs: the Install section now distinguishes the two reload paths — client-half edits in a
link: checkout are hot-reloaded by the default @deepseek-ai/dsh-client-hmr, while add / remove / update still need a dsh web restart.
2026-09-08 — DSH 0.1.2-rc.1 compatibility (slot registration became declaration-gated)
- DSH
0.1.2-rc.1 reworked the web client's slot system: slots.register() is now a pure attachment API and throws unless the target slot has already been declared by a parent entry's children table. The composer subtree — including conversation.composer.dock — is declared lazily by the conversation UI tree, i.e. after plugin loader entries have applied, so the old direct ctx.slots.register(...) call in apply() failed with slot "conversation.composer.dock" is not declared (a parent entry's children table must declare it) and DSH showed Failed to load plugins at startup.
- Registration now goes through
ctx.slots.inject("conversation.composer.dock", () => ctx.slots.register({ name, id, order }, …)) — the same pattern the stock StatsLine uses for the very same slot. slots.inject runs the factory immediately when the slot is already declared, otherwise waits for its (re)declaration, and the whole wait + registration rides the plugin's own fiber for cleanup.
- Nothing else needed to change: the dock slot's standard props (
useSession / useProjection), the [data-composer-card] / data-slot DOM markers and every projection the HUD reads are unchanged in 0.1.2-rc.1 (verified against the installed package sources).
- Docs synced (this README and
README-CN.md).
2026-08-24 — Peak / off-peak windows updated
CLOCK badge now follows the official DeepSeek API peak-valley pricing: peak = Mon–Fri Beijing 09:00-12:00 / 14:00-18:00 (i.e. Mon–Fri 01:00-04:00 / 06:00-10:00 UTC); weekends are always OFF-PEAK (previously weekends inside those windows were wrongly shown as PEAK).- Refactored the check into the pure
isDsApiPeak(date) helper (weekday resolved on the Beijing calendar, so it is correct in any timezone) and exposed it via the test-only __test export.
- Added 3 unit-test groups covering window edges, weekends and the Beijing/UTC day boundary (9 tests total, all green).
- Docs synced (this README,
README-CN.md and the Tuning section).
Upgrading from an older DSH
After DSH moved to declaration-gated slots (0.1.2-rc.1), an install of this
plugin made before that change fails at startup with:
Failed to load plugins
dsh-stats-hud
failed to apply loader entry … (dsh-stats-hud): slot "conversation.composer.dock" is not declared (a parent entry's children table must declare it)
Update the plugin to the fixed version (the 2026-09-08 Changelog entry above), then reload it:
- Installed from a local checkout (
link: dependency): update the
checkout (git pull, or copy the new files over). The client half is
hot-reloaded by @deepseek-ai/dsh-client-hmr into the running page; restart
dsh web only if the plugin's host half or its cordis.patch.yml patch
changed.
- Installed from GitHub or npm: re-resolve the latest version with
dsh plugin --profile web update dsh-stats-hud, or remove and add the
package again, then restart dsh web — a newly resolved install path is
scanned at boot.
Quick sanity check that the fixed version is in place: the client code must
contain the new registration pattern ctx.slots.inject("conversation.composer.dock", …) (see lib/client.js).
If the alert still shows after the restart, hard-refresh the browser page
(Cmd+Shift+R) — the plugin's browser bundle is cached per page load.
Instruments (all-English, LLM terminology)
| Instrument | Data | Full scale | Past full scale |
|---|
CLOCK badge | Local time (24h) + DS API PEAK / DS API OFF PEAK rate | Peak = Mon–Fri Beijing 09:00-12:00 / 14:00-18:00 (i.e. Mon–Fri 01:00-04:00 / 06:00-10:00 UTC); weekends and all other hours are OFF-PEAK (half price) | PEAK orange tint, OFF-PEAK green tint |
STEPS / TURN rolling rows | Steps / turns as odometer drums (like the CONTEXT rows) | — | Drums spin up on mount, roll on change |
LLM / TOOLS dual bar | Two columns (labels over values), bar segments = raw LLM:TOOLS time ratio | No cap — 2:1 time means 2:1 bar | — |
THROUGHPUT gauge | tokens/s (throughput), centered title, combined centered readout (146 tok/s) | Redline auto-scales 200→300→400… (arc ticks follow) | — |
CONTEXT USAGE bar | Context-window usage % with 3 segments: Sys Prompt (gray) / Tools (blue) / Messages (purple) by token ratio | 0-100% | ≥80% whole bar turns solid red; hover shows the three token counts |
CACHE HIT bar | Cache-hit % | 0-100% | <50% red, <80% yellow, ≥80% green |
CONTEXT rolling counter | Three odometer rows: CACHE HIT (green) / CACHE MISSED (orange) / OUTPUT (pink) | Drums spin up from 0 on mount; digits roll up on increase (carry 9→0), down on decrease | — |
While the agent is running the whole panel breathes and bars pulse.
Hovering the CONTEXT USAGE bar pops up a tooltip with the token breakdown:
hover tooltip
Responsive layout
The HUD adapts to the free space right of the chat column (measured live with a ResizeObserver, so sidebar drags, the details drawer and window resizes all count):
| Tier | Condition | Shows |
|---|
full | Window ≥ 800px and free space ≥ 180px | Everything |
mini | Window ≥ 800px and free space < 180px | Clock (short PEAK/OFF PEAK badge) + compact rolling rows (Step/Turn/HIT/MISS/OUT) |
hidden | Window < 800px | Nothing (element stays mounted, display:none) |
The window width is a hard floor: below 800px the panel hides even with room to spare, and only the measured space decides full vs mini (the full panel needs 164px + 12px margin). mini may slightly overlap the chat on narrow windows — safe because the panel is click-through. If the chat column can't be measured, the panel falls back to full.
The mini tier in a narrow window:
mini tier
Requirements
- DeepSeek Harness
dsh (tested on 0.1.0-rc.6 → 0.1.5-rc.1, macOS; since 0.1.2-rc.1 slot registration is declaration-gated and requires the ctx.slots.inject pattern — see Changelog)
- pnpm (for plugin management)
Install
# from a local checkout
dsh plugin --profile web add /path/to/dsh-stats-hud
# or straight from GitHub
dsh plugin --profile web add https://github.com/lauytgary/dsh_hud_plugin
Then restart dsh web (loader entries are scanned at boot) and refresh the page. The package is installed as a link: dependency, so local edits never need a reinstall — and the web profile mounts @deepseek-ai/dsh-client-hmr by default, which stat-polls the client bundle and re-applies the plugin: after editing lib/client.js, the HUD hot-reloads into the running page (no restart, no manual refresh). A restart is only needed when the plugin is added, removed or updated — i.e. when the loader entries themselves change.
The plugin then shows up in Settings → Plugins:
dsh-stats-hud in the plugin list
Uninstall
dsh plugin --profile web remove dsh-stats-hud
How it works
- Registers into the
conversation.composer.dock slot (id dsh-stats-hud, order 1) — only to receive the session-scoped hooks (useSession/useProjection); the panel itself is position: fixed, takes no layout space, and the stock stats line stays untouched. Registration goes through ctx.slots.inject(...), which waits for the slot to be declared by its parent entry (required since DSH made slot registration declaration-gated).
- Data comes from the same projections the stock UI uses:
useProjection("sessionStats"), useProjection("tokenUsage"), useProjection("contextPressure") and useProjection("contextBreakdown") — zero host-side changes.
exports.inject = ["slots"] is mandatory: DSH's ctx is a strict proxy, and accessing an undeclared service throws (cannot get property "locale" without inject).- The panel is
pointer-events: none (click-through); only the CONTEXT USAGE bar re-enables pointer events so its hover tooltip works.
Files
dsh-stats-hud/
├── package.json # dsh.bundle (patch layer) + dsh.client (browser entry)
├── cordis.patch.yml # inserts the plugin into loader entries
├── lib/
│ ├── index.js # host-side no-op (pure browser plugin)
│ └── client.js # browser bundle: HUD components + slot registration
└── test/
└── format.test.js # pure-function unit tests (node:test, zero deps)
lib/client.js is a hand-written loader bundle (window.__ModuleLoader__.load) — no build step needed.
Development & testing
npm test # pure-function unit tests (node:test, no dependencies; Node ≥ 18)
The tests load lib/client.js in a Node VM with a stubbed loader (no DOM
needed) and exercise the pure helpers — formatTokens, formatDuration,
formatTps, tierOf, billedInputTokens, cacheHitPercent. The test-only
__test export is gated behind the DSH_HUD_TEST env var, so the browser
bundle is unaffected.
Tuning
All constants live in lib/client.js:
- Labels: the
L object (all-English LLM terminology)
- Peak hours:
LocalClock delegates to isDsApiPeak(date), which checks the Beijing (UTC+8) weekday bjDow >= 1 && bjDow <= 5 (Mon-Fri) together with bjMin >= 540 && bjMin < 720 (9-12h) / >= 840 && < 1080 (14-18h), where bjMin/bjDow come from new Date(date.getTime() + 8*3600e3) — weekends are always off-peak
MissionRolling: rolling drums for steps/turns (no full scale)ChannelBar: segment ratio = llmMs / (llmMs + toolMs) (no cap)SpeedGauge's redline = 200 (initial; auto-scales in 100 tok/s steps)ContextUsageBar: segment colors and the ≥80% solid-red threshold; the hover tooltip reads systemTokens / toolsTokens / messageTokens from the contextBreakdown projection- Rolling counter:
DRUM (3× 0-9), DRUM_H = 15 (px per digit), RollingValue's carry/borrow formula and mount spin-up
- CSS:
position:fixed; right:12px; tiers in tierOf(space, width) — width < 800 → hidden (window-width floor), space >= 180 → full, else mini (measurement failure falls back to full) — plus the .gsh-root.gsh-* rules; @media (prefers-reduced-motion: reduce) disables pulses and transitions
Publishing to npm (optional)
# remove "private": true from package.json, then
npm publish
# users install with:
dsh plugin --profile web add dsh-stats-hud
Contact
Questions, ideas or issues? Open a discussion on GitHub:
License
MIT
