deepseekplugins

DeepSeek Harness plugin

dsh-usage

Persistent balance badge and token usage panel for the dsh web GUI

UI Enhancements
Jump to install

Source facts

Repository
Aisland-SJL/dsh-usage
Latest update
Aug 18, 2026
Category
UI Enhancements
GitHub stars
20
Format
plugin
Catalog evidence
Upstream dsh.bundle evidence
Evidence path
package.json#dsh.bundle
Checked against
0.1.0-rc.8
Upstream check date
2026-08-20

This evidence comes from the upstream catalog. This site has not installed, run, or security-reviewed the plugin.

Install

Start with a prompt that asks an agent to review the GitHub repository and source. Switch to the command if you want to install it yourself.

Copy this prompt into DSH, Codex, or another agent and ask it to review the GitHub repository and source first.

Do not install or run any commands yet. Read this plugin's GitHub repository, README, and relevant source code. Then answer the questions below clearly and directly so I can decide whether it fits my needs:

1. What is this plugin, and what problem does it solve?
2. Who is it for, and what are its typical use cases?
3. How is it used after installation? Include one minimal example.
4. What known limitations or privacy, security, compatibility, or maintenance risks does it have?
5. Give a clear recommendation: recommend, conditionally recommend, or do not recommend, with reasons.

Distinguish statements documented by the repository, inferences from source code, and unknowns. If evidence is insufficient, say so explicitly. Do not guess or simply repeat the README.

GitHub: https://github.com/Aisland-SJL/dsh-usage
Plugin: dsh-usage
Author: Aisland-SJL

Check the source files

Read the README and other files from this plugin directory before installing.

File explorer3 files
README.mdSource Β· read only

🌊 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).

![README-δΈ­ζ–‡](README.zh-CN.md) ![License](LICENSE)

✨ 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.

<table><tr> <td width="44%"><img src="docs/images/dock.png" alt="dsh-usage dock" width="100%"></td> <td>

  • 🟒 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

</td> </tr></table>

πŸŽ›οΈ 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.

<table><tr> <td>

WidgetWhat it does
πŸ’³ BalanceBig number on the left, available / topped-up / granted rows on the right; provider switchable
πŸ“Š TodayToday's tokens plus input / output / cache-read breakdown
πŸ“ˆ This monthMonthly tokens plus the same breakdown
🎯 Cache hitToday's and all-time cache hit rates
↔️ Channel shareDSH channel vs Claude Code channel ratio bar
πŸ“œ Usage logLast 14 days per-day list, click to drill into per-model detail
πŸ”₯ Activity heatmap28-day Γ— 6-band dot grid (dates across, 0–24h down)

</td> <td width="46%"><img src="docs/images/panel.png" alt="dsh-usage panel" width="100%"></td> </tr></table>

🎨 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.

<p align="center"><img src="docs/images/customizer.png" alt="dsh-usage customizer" width="78%"></p>

At a glance

FeatureNotes
πŸ’³Persistent dockPinned compacts always visible; collapses into a balance pill when the sidebar folds
🎨Everything customizableWidgets: pin / collapse / hide / drag-reorder with a dashed placeholder and glide animation; accent, background, opacity; persisted in localStorage
πŸ“ŠBalance & usage panelProvider picker, balance breakdown, today/month totals in k/M/B units, cache hit, usage log with per-model drilldown
πŸ”₯Activity heatmapGitHub-style dots: 28 days Γ— 6 four-hour bands with date labels
↔️Channel shareDSH channel vs Claude Code channel (incremental JSONL aggregation of ~/.claude/projects)
πŸ”„Background refreshRefresh at startup, then every 5 minutes: balances, DSH tokens, Claude Code aggregation
πŸ”’Local-only securityThree 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

ProviderUpstream endpointDefault credential ref
DeepSeekGET {origin}/user/balanceDEEPSEEK_API_KEY
OpenRouterGET {origin}/api/v1/creditsOPENROUTER_MANAGEMENT_KEY
Moonshot / KimiGET {origin}/v1/users/me/balancepi-ai provider apiKeyEnv
Z.ai / GLMGET {origin}/api/paas/v4/balanceZAI_API_KEY

API

MethodPathResponse
GET/api/usage/providersProvider list, balance scheme, and status summary
GET/api/usage/balance?provider=<id>Unified balance snapshot; refresh=1 forces an upstream query
GET/api/usage/usagePer-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](LICENSE)

Back to searchOpen GitHub repository

More related plugins

View category