Skip to content
Back to search

dsh-usage

🌊 Persistent dock & fully-customizable balance/usage panel for DeepSeek Harness β€” activity heatmap, dual-channel comparison, local-only & privacy-first

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aisland-sjl--dsh-usage/badge.svg)](/listings/aisland-sjl--dsh-usage)

HTML

<a href="/listings/aisland-sjl--dsh-usage"><img src="/api/listings/aisland-sjl--dsh-usage/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**v0.3.1 targets DeepSeek Harness 0.2.0-rc.2**, on Web and official Windows Desktop. Legacy service branches remain, but a full 0.1.x-host regression has not been performed: keep v0.3.0 on older hosts rather than assuming universal compatibility. Desktop platforms other than Windows have not been tested on real machines.

Desktop uses the client `platform: web` contract, but installation belongs to the `desktop` profile and must use that app's bundled CLI while Desktop is fully quit. Open the app manually afterward; do not kill or restart it automatically. Update prompts select the active profile. Plugin appearance settings are origin-specific, even when profiles share DSH_HOME. Offline tests do not establish acceptance for every account, historical session, or Desktop feature.

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

Alternatively, use the fixed-name Release TGZ (available after publication; use a tag-specific versioned asset for a reproducible installation):

dsh plugin --profile web add "https://github.com/Aisland-SJL/dsh-usage/releases/latest/download/dsh-usage.tgz"

For Desktop, fully quit first and run this with **that application's bundled dsh CLI**, not the Web CLI:

dsh plugin --profile desktop add "https://github.com/Aisland-SJL/dsh-usage/releases/latest/download/dsh-usage.tgz"

The runtime dependency is `@deepseek-ai/dsh-client-ui-primitives@0.2.0-rc.2`; normal package installation resolves it without manually adding official components. For a linked checkout, check the active profile's dependencies against its host. Do not install another version of an official UI component just to suppress a warning.

For Web, fully restart `dsh web` and hard-refresh; for Desktop, open the app manually. Update / remove commands for GitHub-sourced installations (for TGZ upgrades, repeat the corresponding `add` command):

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 161 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # 🌊 dsh-usage
  2. A **persistent floating dock**, a **fully customizable balance / token-usage panel**, an **activity heatmap**, and a **dual-channel usage comparison** for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web GUI (`dsh web`) and official Windows Desktop. See the host scope below.
  3. [![README-δΈ­ζ–‡](https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87-crimson?style=flat-square)](README.zh-CN.md)
  4. [![License](https://img.shields.io/badge/license-MIT-2da44e?style=flat-square)](LICENSE)
  5. ## ✨ Feature tour
  6. ### 🌊 Persistent dock
  7. 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.
  8. <table><tr>
  9. <td width="44%"><img src="docs/images/dock.png" alt="dsh-usage dock" width="100%"></td>
  10. <td>
  11. - 🟒 **Balance** β€” green when healthy, red when drained
  12. - πŸ“Š **Today / Month / Cache hit** β€” glanceable token stats
  13. - βš™ **Gear** opens the panel Β· ↻ refresh re-queries instantly
  14. - 🧲 **Mirrors your pins** β€” every change applies immediately
  15. </td>
  16. </tr></table>
  17. ### πŸŽ›οΈ Detail panel β€” all seven widgets
  18. A two-column card layout; every widget has a detail and a compact form, and can be drag-reordered, collapsed, hidden, or pinned.
  19. <table><tr>
  20. <td>
  21. | Widget | What it does |
  22. | --- | --- |
  23. | πŸ’³ **Balance** | Big number on the left, available / topped-up / granted rows on the right; provider switchable |
  24. | πŸ“Š **Today** | Today's tokens plus input / output / cache-read breakdown |
  25. | πŸ“ˆ **This month** | Monthly tokens plus the same breakdown |
  26. | 🎯 **Cache hit** | Today's and all-time cache hit rates |
  27. | ↔️ **Channel share** | DSH channel vs Claude Code channel ratio bar |
  28. | πŸ“œ **Usage log** | Last 14 days per-day list, click to drill into per-model detail |
  29. | πŸ”₯ **Activity heatmap** | 28-day Γ— 6-band dot grid (dates across, 0–24h down) |
  30. </td>
  31. <td width="46%"><img src="docs/images/panel.png" alt="dsh-usage panel" width="100%"></td>
  32. </tr></table>
  33. ### 🎨 Everything customizable
  34. 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.
  35. <p align="center"><img src="docs/images/customizer.png" alt="dsh-usage customizer" width="78%"></p>
  36. ## At a glance
  37. | | Feature | Notes |
  38. | --- | --- | --- |
  39. | πŸ’³ | Persistent dock | Pinned compacts always visible; collapses into a balance pill when the sidebar folds |
  40. | 🎨 | Everything customizable | Widgets: pin / collapse / hide / drag-reorder with a dashed placeholder and glide animation; accent, background, opacity; persisted in localStorage |
  41. | πŸ“Š | Balance & usage panel | Provider picker, balance breakdown, today/month totals in k/M/B units, cache hit, usage log with per-model drilldown |
  42. | πŸ”₯ | Activity heatmap | GitHub-style dots: 28 days Γ— 6 four-hour bands with date labels |
  43. | ↔️ | Channel share | DSH channel vs Claude Code channel (incremental JSONL aggregation of `~/.claude/projects`) |
  44. | πŸ”„ | Background refresh | Refresh at startup, then every 5 minutes: balances, DSH tokens, Claude Code aggregation |
  45. | πŸ”’ | 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 |
  46. UI supports Chinese and English. Balance requests resolve keys in memory through Harness's credential service; keys are not included in plugin caches or browser responses.
  47. ## Quick start
  48. **v0.4.0 supports DeepSeek Harness 0.1.x and 0.2.x**, on Web and official Windows Desktop. Verified in a real desktop run on **0.2.1-rc.3** (the 0.2 path: `open('read')` handle, 85/87 sessions counted, endpoint 200); 0.2.2-alpha is untested. Live sessions are read through whichever Session API the host exposes (`events`, `snapshotEvents`, or `ownEvents`); persisted logs use `readFrom` (0.1.x) or the 0.2 read handle. A host that exposes no readable log API degrades to a reported skip instead of an HTTP 500 β€” it is not silently counted as zero. Real-machine 0.1.x verification is pending community retest; Desktop platforms other than Windows have not been tested on real machines.
  49. Desktop uses the client `platform: web` contract, but installation belongs to the `desktop` profile and must use that app's bundled CLI while Desktop is fully quit. Open the app manually afterward; do not kill or restart it automatically. Update prompts select the active profile. Plugin appearance settings are origin-specific, even when profiles share DSH_HOME. Offline tests do not establish acceptance for every account, historical session, or Desktop feature.
  50. ```bash
  51. dsh plugin --profile web add "github:Aisland-SJL/dsh-usage"
  52. ```
  53. Alternatively, use the fixed-name Release TGZ (available after publication; use a tag-specific versioned asset for a reproducible installation):
  54. ```bash
  55. dsh plugin --profile web add "https://github.com/Aisland-SJL/dsh-usage/releases/latest/download/dsh-usage.tgz"
  56. ```
  57. For Desktop, fully quit first and run this with **that application's bundled dsh CLI**, not the Web CLI:
  58. ```bash
  59. dsh plugin --profile desktop add "https://github.com/Aisland-SJL/dsh-usage/releases/latest/download/dsh-usage.tgz"
  60. ```
  61. The runtime dependency is `@deepseek-ai/dsh-client-ui-primitives@0.2.0-rc.2`; normal package installation resolves it without manually adding official components. For a linked checkout, check the active profile's dependencies against its host. Do not install another version of an official UI component just to suppress a warning.
  62. For Web, fully restart `dsh web` and hard-refresh; for Desktop, open the app manually. Update / remove commands for GitHub-sourced installations (for TGZ upgrades, repeat the corresponding `add` command):
  63. ```bash
  64. dsh plugin --profile web update dsh-usage
  65. dsh plugin --profile web remove dsh-usage
  66. ```
  67. ## Credentials
  68. Configure credential references through Harness. Older hosts stored these in `~/.dsh/.credentials.yaml`; do not assume that path on 0.2 or a custom `DSH_HOME`:
  69. ```yaml
  70. DEEPSEEK_API_KEY: sk-your-key-here # official DeepSeek route
  71. OPENROUTER_MANAGEMENT_KEY: sk-or-v1-... # OpenRouter account (Management Key, not the inference key)
  72. ZAI_API_KEY: your-zai-key # Z.ai open platform
  73. ```
  74. 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.
  75. On 0.2 the provider directory addresses redacted live settings by entry id. Supported pi-ai routes may also use an API-key record; OAuth/grant payloads are not interpreted. OpenRouter still requires a Management Key, not its stored inference key. A missing endpoint or usable key is reported as not configured, not silently borrowed from another route.
  76. For isolated tests set the plugin entry's `config.balanceEnabled: false` to prevent credential resolution and upstream balance requests (default: enabled). Set `CLAUDE_CONFIG_DIR` explicitly to a synthetic test directory; otherwise the existing default still scans `~/.claude/projects`. Token cache v4 rebuilds older caches. On 0.2 unchanged session revisions are cached, changed sessions are refolded through read-only handles, and inherited fork history is not billed twice. Real account queries and paid model runs are separate acceptance work.
  77. Unreadable sessions no longer block the rest of the aggregation. The response's `coverage` describes the sessions listed by the host: `complete`, `partial`, or `unavailable`, with counted/skipped sessions and per-session reasons (`unsupported-format`, `unsupported-session-api`, `unsupported-host`, `read-failed`). Partial totals show the exact readable subtotal plus an expandable coverage notice β€” values are not prefixed with "β‰₯". When every skipped session is a legacy `unsupported-format` log, the notice stays quiet (no warning dot, muted row) and the channel-share widget still renders; actionable reasons (`read-failed`, `unsupported-session-api`, `unsupported-host`) keep the warning dot and block the ratio. If no session can be read, totals are unavailable (`total: null`, β€œβ€”β€ in the UI), not zero. Failed records are retried without retaining stale counts. This does not repair unsupported historical formats or rewrite their logs. A failure to list sessions still returns an error.
  78. ## Supported providers
  79. | Provider | Upstream endpoint | Default credential ref |
  80. | --- | --- | --- |
  81. | DeepSeek | `GET {origin}/user/balance` | `DEEPSEEK_API_KEY` |
  82. | OpenRouter | `GET {origin}/api/v1/credits` | `OPENROUTER_MANAGEMENT_KEY` |
  83. | Moonshot / Kimi | `GET {origin}/v1/users/me/balance` | pi-ai provider `apiKeyEnv` |
  84. | Z.ai / GLM | `GET {origin}/api/paas/v4/balance` | `ZAI_API_KEY` |
  85. ## API
  86. | Method | Path | Response |
  87. | --- | --- | --- |
  88. | `GET` | `/api/usage/providers` | Provider list, balance scheme, and status summary |
  89. | `GET` | `/api/usage/balance?provider=<id>` | Unified balance snapshot; `refresh=1` forces an upstream query |
  90. | `GET` | `/api/usage/usage` | Per-day/per-model token aggregates, cache hit rates, 24-hour buckets (`days[].hours`), coverage status (`coverage`), and the Claude Code channel (`claude`) |
  91. Non-GET requests get `405`, non-loopback callers get `403`; every response is JSON with `Cache-Control: no-cache`.
  92. ## Development & testing
  93. ```bash
  94. npm install # react/react-dom/jsdom for offline tests only
  95. npm run check # syntax checks for every module and script
  96. npm test # 118 offline tests: balance schemes, token folding, server boundary, client, e2e flows, Claude aggregation, package + 0.2 contracts, host compatibility
  97. npm run test:compat # 0.1.x / 0.1.5-shaped Session API contracts
  98. npm run test:package # runtime dependency + client inject contract
  99. ```
  100. 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`.
  101. ## Privacy & security
  102. - API keys never enter browser responses, plugin caches, or logs; they are resolved at request time through Harness's credentials seam.
  103. - 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.
  104. - Usage caches under `~/.dsh/storages/` hold only aggregated token numbers and fold cursors β€” no prompts, no replies.
  105. - Claude Code logs are parsed line-by-line and discarded; only aggregated numbers reach the cache.
  106. - Do not expose these endpoints through a reverse proxy to LAN or the public internet.
  107. ## Credits
  108. - [Ychris12138/dsh-usage-stats](https://github.com/Ychris12138/dsh-usage-stats) (MIT): reference for balance schemes, token folding semantics, bundle plugin structure, and the security boundary.
  109. ## License
  110. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.