A native dsh bundle plugin that shows a live DeepSeek API balance, today's usage and per-turn spend as a draggable cartoon-whale widget in the dsh web UI.
DSH integration
Native runtime
Author-claimed
Safety audit
Unaudited
Last verified
2026-08-22
License
MIT
01What can it help you accomplish?
Keep an eye on your DeepSeek API balance and spend inside the dsh web UI
A resident cartoon-whale widget in the bottom-right of the dsh Web UI shows the live DeepSeek API balance (auto-refresh every 60s + click to refresh, with a rolling number animation), today's usage and per-turn consumption after each conversation, plus drag / edge-snap and playful animations
DeepSeek API users who want an always-visible balance / spend readout while working in the dsh web UI
Track today's spend without extra credentials
The default 'whale ledger' mode computes today's usage from balance deltas entirely locally (no platform token needed); an optional 'real-time token' mode uses a platform session token for hourly token-based, peak/valley-priced usage
Cost-conscious users who want per-turn and daily DeepSeek spend visibility with minimal setup
02How to install into DeepSeek Harness
Prerequisites
- DeepSeek Harness with the web interface (`dsh web`) and a web profile
- A `DEEPSEEK_API_KEY` configured in dsh credentials (required to fetch the balance)
Installation steps
- 01
Install from npm: `dsh plugin --profile web add dsh-whale-widget` (or, for a local clone, run `dsh plugin --profile web add link:.` from the repo root — not `link:.<subdir>`)
$ dsh plugin --profile web add dsh-whale-widget
- 02
Restart `dsh web`, then press F5 in the browser
$ dsh web
- 03
(Optional) Configure `DEEPSEEK_API_KEY` in dsh credentials if not already set; the widget appears bottom-right automatically
Verify the integration
- Run `dsh --profile web --dump-config` and confirm `dsh-whale-widget` is listed under bundles
- Curl `http://127.0.0.1:3080/dsh-whale/balance.json` — it should return 200 with `totalBalance` — and the whale widget should appear in the bottom-right after F5
Rollback
- Uninstall with `dsh plugin --profile web remove dsh-whale-widget`
03DSH integration and capability boundaries
Native DeepSeek Harness (`dsh`) bundle plugin named `dsh-whale-widget`. It mounts a resident cartoon-whale widget in the bottom-right corner of the dsh Web UI that shows the DeepSeek API balance, today's usage and per-turn consumption, auto-enabled every time the interface opens. Install / uninstall via `dsh plugin`.
Live balance widget
the dsh Web UI (bottom-right corner)→shows DeepSeek API balance with a 60s auto-refresh plus click-to-refresh, a rolling-number animation on change, and graceful fallback to the last balance during transient network jitter
Today's usage (two modes)
observed balance drops, or (optional) the DeepSeek platform usage API→today's spend via the default 'whale ledger' (local balance-delta accounting, no token) or the optional 'real-time token' mode (platform usage API with built-in peak/valley hourly pricing)
Per-turn consumption
local dsh session events (turn end)→after each conversation turn, pops the precise usage-based amount for that turn (real model usage, not an estimate) — no platform token required
Widget UX & playfulness
mouse / menu interactions with the widget→drag + four-edge quarter-snap (left-snap mirrors horizontally), press-Q bounce, a hamburger menu (size 0.6–2.5x, sound toggle, usage mode, bubble toggles, auto-close seconds), optional sounds (silent degrade if mp3 missing) and random whale lines
04Who is it for? When not to use it?
Good for
- DeepSeek API users who want an always-visible balance / spend readout while working in the dsh web UI
- Cost-conscious users who want per-turn and daily DeepSeek spend visibility with minimal setup
Not for
- `DEEPSEEK_API_KEY` is required (used to fetch balance from api.deepseek.com/user/balance). `DEEPSEEK_PLATFORM_TOKEN` is optional — it is a DeepSeek platform web session token (not the `sk-` API key), only valid while logged into the platform, and only needed for the real-time token usage mode. Re-login may require re-fetching it.
05Compatibility, maintenance and safety notes
- Native dsh bundle plugin: requires the DeepSeek Harness web interface (`dsh web`) and a web profile. Install with `dsh plugin --profile web add dsh-whale-widget` (or `link:.` from the repo root), then restart `dsh web` and refresh the browser. It only renders inside the dsh Web UI.
- `DEEPSEEK_API_KEY` is required (used to fetch balance from api.deepseek.com/user/balance). `DEEPSEEK_PLATFORM_TOKEN` is optional — it is a DeepSeek platform web session token (not the `sk-` API key), only valid while logged into the platform, and only needed for the real-time token usage mode. Re-login may require re-fetching it.
- The default whale-ledger mode stores daily accounting locally in `$DSH_HOME/.dshw-usage.json` (kept 30 days) and needs no platform token. The real-time token mode sends requests to DeepSeek's platform usage API using the optional session token.
MIT · actively maintained (latest release v0.2.7, 2026-08-22)
06Frequently asked questions
How do I install the whale widget?
Run `dsh plugin --profile web add dsh-whale-widget` (npm) in your web profile, then restart `dsh web` and press F5. If you cloned the repo, use `dsh plugin --profile web add link:.` from the repo root (not a `link:.<subdir>` path). The widget then appears bottom-right automatically.
What credentials does it need?
Only `DEEPSEEK_API_KEY` is required — it's used to fetch the balance. `DEEPSEEK_PLATFORM_TOKEN` is optional and only needed for the real-time token usage mode; the default whale-ledger mode works with just the API key.
How is today's usage calculated?
In the default 'whale ledger' mode, the whale computes today's usage from observed balance drops, entirely locally (no token). The optional 'real-time token' mode calls DeepSeek's platform usage API and converts to amount using a built-in peak/valley hourly pricing table.
Does it show per-turn cost?
Yes. It listens to local dsh session events and, after each conversation turn ends, pops the precise usage-based amount for that turn — using the real model usage, not an estimate, and without needing any platform token.
How do I verify it works, and how do I uninstall it?
Verify: `dsh --profile web --dump-config` should list `dsh-whale-widget` under bundles, `curl http://127.0.0.1:3080/dsh-whale/balance.json` returns 200 with `totalBalance`, and the whale shows bottom-right after F5. Uninstall with `dsh plugin --profile web remove dsh-whale-widget`.
07Related DSH workflows
dsh-web
by zhu1090093659
DeepSeek Harness (DSH) Web Plugin Aggregation Ecosystem · Everything is a plugin, distributed via the Creative Workshop
petdex
by crafter-station
A public gallery of animated pets for Codex, Claude Code, DeepSeek Harness, Hermes, OpenCode, Gemini CLI, and more.
j-space-cognition-suite-v3.7
by tiger3807861189
AI cognitive-enhancement skills for agent harnesses inspired by Anthropic's global workspace research. Adds inference-time control and reasoning tools for DeepSeek Harness, Claude Code, Codex and OpenCode.
dsh-deep-whale
by small-tailqwq
DSH Web GUI 鲸鱼娘主题皮肤（深海女仆工坊 maid-atelier：亮/暗双模式）
08Data and sources
DeepSeek Harness（DSH）Web 界面右下角的常驻余额挂件：小鲸鱼气泡图 + DeepSeek API 余额 + 今日已用 + 每轮对话消耗统计，每次打开界面自动启用。
本项目是标准 DSH 插件包，可通过 `dsh plugin` 安装/卸载。
dsh plugin --profile web add dsh-whale-widget
This page is generated from the project’s public documentation, repository metadata and a structured parse of DSH Plugins; last verified on 2026-08-22. Found an error? Submit a correction.
Best DeepSeek Harness Plugins
Twelve plugins worth installing first — picked from the whole catalog, across every category.