Open-source project
MeteorNOX/DeepSeek-Balance-Whale-Widget avatar
MeteorNOX/DeepSeek-Balance-Whale-Widget

DeepSeek Balance Whale Widget: a DSH plugin that infers your daily spend from balance drops

DeepSeek Harness (DSH) widget: a cute whale character living in the bottom-right corner of the DSH interface that watches your DeepSeek account balance for you. Bounces like QQ, supports drag-to-dock, flips when docked on the left, and has rolling number animations; auto-enabled with the interface.

7,246 stars237 forksJavaScriptMIT

At a glance

What is it?
The DeepSeek Balance Whale Widget is an MIT-licensed DeepSeek Harness bundle plugin that parks a whale in the corner of the DSH web interface and shows your DeepSeek balance, today's spend and per-turn cost. Its accounting is built on watching the balance move, which works without any session token but needs manual correction when money arrives or leaves for reasons other than API calls.
Who is it for?
This widget suits DeepSeek Harness users who want their DeepSeek balance, daily spend and per-turn cost visible without opening the platform console, and who are happy with spend figures derived from balance changes. It does not suit Codex desktop users, who need the separate Codex-Whale-Public repository, or anyone who needs exact billing for providers without a balance endpoint.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 35 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • MeteorNOX/DeepSeek-Balance-Whale-Widget7,246 ★ · +5,075
Star history
Repository2026-09-112026-11-15
MeteorNOX/DeepSeek-Balance-Whale-Widget2.2k7.2k

5,075 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A DSH bundle plugin installed with one dsh plugin command

The widget is a standard DeepSeek Harness bundle plugin, published under the package name dsh-whale-widget with lib/index.js as its entry and a cordis.patch.yml bundle patch. It appears automatically every time the DSH web interface opens, and it needs no session token. The recommended install pulls the published npm release:

code
dsh plugin --profile web add dsh-whale-widget

You can also install straight from the repository:

code
dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget

That second form installs whatever main looks like at that moment and does not follow published versions. The two sources share one package name, so installing both makes them coexist and conflict. If you started with github: and want to move to the npm name, remove it first:

code
dsh plugin --profile web remove dsh-whale-widget

The desktop client cannot be set up through the web profile

The same package on main also supports the official DSH desktop client built on Electron, but the install path differs. The desktop client reads the desktop profile, so installing with --profile web does nothing for it, and the CLI rejects --profile desktop outright. The project's instruction is to ask DSH itself to install the plugin from inside a desktop session. The practical consequence is that a script which installs the widget for web users cannot be reused for desktop users, and anyone who runs the web command and expects the whale to appear in the desktop app will see nothing.

The Codex whale moved out and the two lines are incompatible

A Codex desktop version of the whale used to live here. It has moved to its own repository at github.com/Yang-huai406/Codex-Whale-Public, with its development history, past versions and author credits carried over, and future Codex releases and issue reports happen there. Existing Codex users do not need to reinstall. The two lines do not mix: the Codex build cannot be added to the DSH web page with dsh plugin add, and this repository's plugin does not run inside the Codex desktop app. When reporting Codex problems, the project asks for version, system and reproduction steps, and warns against uploading keys, full configs or unredacted logs.

Balance comes from your API key first, then your DSH login

The balance refreshes every 60 seconds, and clicking the whale forces a refresh. Changes roll in with a number animation, and brief network failures fall back to the last known balance instead of showing an error. There are two ways to read it, and the API key wins: first the DEEPSEEK_API_KEY stored in DSH credentials, and if that is missing, the DeepSeek account you signed into through DSH settings under account and balance. The second route means you do not have to create a key on the DeepSeek platform just to see your balance. The bubble can show total balance, gift credit and top-up balance as separate modules; the split modules show a dash when the value cannot be read and 0.00 only when it is really zero.

Today's spend is observed from balance drops, not billing records

The daily spend figure needs no token because it is inferred: every drop in the DeepSeek balance counts as consumption, and every rise, such as a top-up or gift credit, is recorded separately so it does not cancel out spend already counted. When the widget sees the balance rise it flags a pending balance adjustment, which you settle in the DeepSeek built-in settings under balance calibration by entering the real amount credited and any deductions that were not API calls. Both observed spend and calibration are scoped to the DeepSeek account behind that key and exclude other providers; a separate local model cost figure estimates spend across all models. The consequence is that any balance movement not caused by your DSH session lands in the spend figure until you correct it. Records are kept per turn for 90 days or up to 20,000 entries, daily summaries for 365 days, with older data moved to .dshw-usage-archive.json. Amounts are tracked to 8 decimal places and displayed to two.

Per-turn cost and the peak-hour clock

The widget listens to local DSH session events and converts each turn's real usage, split into input, cache, output and reasoning tokens, into a cost bubble when the turn ends. The bubble can be switched off, and its auto-close time is configurable, with 0 meaning it stays until dismissed; its content is modular and refers to the amount as {cost}. A peak and off-peak module shows the current DeepSeek pricing window: weekday peak hours are 9:00 to 12:00 and 14:00 to 18:00 Beijing time, and since 23 August 2026 weekends are off-peak all day. It supports a status label, a countdown and several display styles.

Other providers often have no balance endpoint, so the widget estimates

Beyond DeepSeek, you can add other providers under the model section of the accounting window, each with its own balance warning, daily budget and quota. There are 34 provider templates. Some can query a real balance or quota, including OpenRouter, Kimi and Moonshot, StepFun, Novita, the Zhipu GLM Coding Plan, MiniMax Coding, OpenAI-compatible relays such as OneAPI and New API, and OpenCode Go with its 5-hour, weekly and monthly windows. Many cannot, because the provider offers no balance lookup by API key: OpenAI, Anthropic Claude, Google Gemini, xAI Grok, Groq, Mistral AI, Together AI, Fireworks AI, DeepInfra, Cerebras, several Chinese clouds, and local models through Ollama or LM Studio. For those, the widget validates the key against a probeUrl, shows a dash for balance, and estimates daily spend from session events. Keys go into the DSH credential service; the config file stores only the credential name, such as OPENROUTER_API_KEY.

Bubble layout caps and the docking default that surprises people

Bubbles are built from modules: text, links, weighted random sentences, images, weighted random images, balance values, the peak window and the conversation name. Layout has hard limits. A row holds at most 6 modules, a bubble holds at most 6 rows, and an image module takes a whole row with only one allowed per bubble. Clicks can step through a sequence of bubbles, and two bubbles can be paired as weighted A and B choices. Docking also has a default worth knowing: the whale snaps to screen edges, flipping horizontally when docked left, but the top docking zone defaults to 0, which means off. To enable it, open the docking settings, choose proportional or absolute docking, set the top value above zero and confirm; large widgets need a bigger zone because docking triggers when the widget's center enters it. Releases v0.4.0, v0.4.1 and v0.4.2 all shipped on 11 October 2026, the date of the last push.

Editorial conclusion

This widget suits DeepSeek Harness users who want their DeepSeek balance, daily spend and per-turn cost visible without opening the platform console, and who are happy with spend figures derived from balance changes. It does not suit Codex desktop users, who need the separate Codex-Whale-Public repository, or anyone who needs exact billing for providers without a balance endpoint. Before installing, pick either the npm name or the github: source and stick to it, and on the official desktop client let DSH install it from a desktop session instead of using the web profile.

Frequently asked questions

Does the DeepSeek Balance Whale Widget need a DeepSeek API key?

No. It uses DEEPSEEK_API_KEY from DSH credentials if present, and otherwise falls back to the DeepSeek account you signed into in DSH settings, so you do not need to create a key on the platform.

How do I install the DeepSeek Balance Whale Widget?

For the DSH web interface, run dsh plugin --profile web add dsh-whale-widget. On the official desktop client, ask DSH to install it from a desktop session, because the CLI rejects --profile desktop.

Can I use the DeepSeek Balance Whale Widget in the Codex desktop app?

Not from this repository. The Codex version moved to github.com/Yang-huai406/Codex-Whale-Public, and the two versions are not compatible with each other.

Official sources

  1. Issues
  2. License: MIT
  3. MeteorNOX/DeepSeek-Balance-Whale-Widget on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/meteornox-deepseek-balance-whale-widget.svg)](https://hysenlabs.com/projects/meteornox-deepseek-balance-whale-widget)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/meteornox-deepseek-balance-whale-widget.svg)](https://hysenlabs.com/projects/meteornox-deepseek-balance-whale-widget)

Was this useful?