🌊 dsh-usage

A persistent floating dock, a fully customizable balance / token-usage panel, an activity heatmap, and a dual-channel usage comparison for the DeepSeek Harness Web GUI (dsh web).

✨ Feature tour

🌊 Persistent dock

Your key numbers stay visible at all times — balance glows green (red only when out of credit), rows are separated by hairlines, and a settings gear plus one-click refresh sit in the corner. When the sidebar collapses, the dock folds into a tiny balance pill.

🟢 Balance — green when healthy, red when drained
📊 Today / Month / Cache hit — glanceable token stats
⚙ Gear opens the panel · ↻ refresh re-queries instantly
🧲 Mirrors your pins — every change applies immediately

🎛️ Detail panel — all seven widgets

A two-column card layout; every widget has a detail and a compact form, and can be drag-reordered, collapsed, hidden, or pinned.

Widget	What it does
💳 Balance	Big number on the left, available / topped-up / granted rows on the right; provider switchable
📊 Today	Today's tokens plus input / output / cache-read breakdown
📈 This month	Monthly tokens plus the same breakdown
🎯 Cache hit	Today's and all-time cache hit rates
↔️ Channel share	DSH channel vs Claude Code channel ratio bar
📜 Usage log	Last 14 days per-day list, click to drill into per-model detail
🔥 Activity heatmap	28-day × 6-band dot grid (dates across, 0–24h down)

🎨 Everything customizable

Accent (presets + color picker), background, and panel opacity are adjustable live. Drag-reorder, pin, collapse, hide — every number presents your way, echoing DeepSeek Harness's "everything is a plugin" spirit.

dsh-usage customizer

At a glance

	Feature	Notes
💳	Persistent dock	Pinned compacts always visible; collapses into a balance pill when the sidebar folds
🎨	Everything customizable	Widgets: pin / collapse / hide / drag-reorder with a dashed placeholder and glide animation; accent, background, opacity; persisted in localStorage
📊	Balance & usage panel	Provider picker, balance breakdown, today/month totals in k/M/B units, cache hit, usage log with per-model drilldown
🔥	Activity heatmap	GitHub-style dots: 28 days × 6 four-hour bands with date labels
↔️	Channel share	DSH channel vs Claude Code channel (incremental JSONL aggregation of `~/.claude/projects`)
🔄	Background refresh	Refresh at startup, then every 5 minutes: balances, DSH tokens, Claude Code aggregation
🔒	Local-only security	Three loopback-only GET endpoints; credentials resolved server-side; upstream forced HTTPS with DNS pinning; Claude logs aggregate numbers only — message text never leaves the machine

UI supports Chinese and English. Credentials come from Harness's ~/.dsh/.credentials.yaml; the plugin never reads, caches, or echoes secrets.

Quick start

Requires a DeepSeek Harness web profile (@deepseek-ai/dsh >= 0.1.0-rc.6).

dsh plugin --profile web add "github:Aisland-SJL/dsh-usage"

Restart dsh web, hard-refresh the browser, and the dock appears at the bottom-left. Update / remove:

dsh plugin --profile web update dsh-usage
dsh plugin --profile web remove dsh-usage

Credentials

Balance providers read credential references from ~/.dsh/.credentials.yaml:

DEEPSEEK_API_KEY: sk-your-key-here            # official DeepSeek route
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-...       # OpenRouter account (Management Key, not the inference key)
ZAI_API_KEY: your-zai-key                     # Z.ai open platform

Moonshot / Kimi profiles under llm-pi-ai are discovered automatically and reuse their apiKeyEnv. Providers without a public balance API show an explicit "no public balance interface" state — never a guess.

Supported providers

Provider	Upstream endpoint	Default credential ref
DeepSeek	`GET {origin}/user/balance`	`DEEPSEEK_API_KEY`
OpenRouter	`GET {origin}/api/v1/credits`	`OPENROUTER_MANAGEMENT_KEY`
Moonshot / Kimi	`GET {origin}/v1/users/me/balance`	pi-ai provider `apiKeyEnv`
Z.ai / GLM	`GET {origin}/api/paas/v4/balance`	`ZAI_API_KEY`

API

Method	Path	Response
`GET`	`/api/usage/providers`	Provider list, balance scheme, and status summary
`GET`	`/api/usage/balance?provider=<id>`	Unified balance snapshot; `refresh=1` forces an upstream query
`GET`	`/api/usage/usage`	Per-day/per-model token aggregates, cache hit rates, 24-hour buckets (`days[].hours`), and the Claude Code channel (`claude`)

Non-GET requests get 405, non-loopback callers get 403; every response is JSON with Cache-Control: no-cache.

Development & testing

npm install           # react/react-dom/jsdom for offline tests only
npm run check         # syntax checks for every module and script
npm test              # 81 offline tests: balance schemes, token folding, server boundary, client, e2e flows, Claude aggregation

Tests are fully offline — no network, and the real ~/.dsh is never touched (server tests redirect DSH_HOME to a temp dir). Dry-run the real Claude data: node scripts/validate-claude.mjs.

Privacy & security

API keys never enter browser responses, plugin caches, or logs; they are resolved at request time through Harness's credentials seam.
Upstream balance queries: HTTPS enforced, DNS pre-resolved and private/loopback ranges rejected, connections pinned to the checked address (DNS-rebinding defense), 1 MiB response cap, 15 s timeout.
Usage caches under ~/.dsh/storages/ hold only aggregated token numbers and fold cursors — no prompts, no replies.
Claude Code logs are parsed line-by-line and discarded; only aggregated numbers reach the cache.
Do not expose these endpoints through a reverse proxy to LAN or the public internet.

Credits

Ychris12138/dsh-usage-stats (MIT): reference for balance schemes, token folding semantics, bundle plugin structure, and the security boundary.

License

MIT