Preface

When running agents, writing code, or calling APIs with DeepSeek Harness (DSH), the two biggest concerns are watching your balance silently dwindle and having to switch out to check the platform just to see how much you’ve used. The DSH web interface focuses on conversation and tool orchestration, so account information isn’t always front and center. The DeepSeek Balance Whale Widget (package name dsh-whale-widget), maintained by MeteorNOX in the community, places a cute, bouncy whale-girl in the bottom-right corner of the interface: your balance, today’s usage, and per-conversation consumption are all visible right there, automatically enabling when the interface opens. This plugin has garnered around 884 stars on GitHub, making it one of the more popular client-side DSH plugins.

This article is compiled based on verification from the SkillHub Plugin Directory Page and the GitHub Repository README, intended for you to install and try out in your DSH environment.

What Is This

DSH Whale Balance Widget is a standard DSH bundle plugin: it runs whenever the DSH web interface is opened, displaying the DeepSeek API balance in the bottom-right corner, along with today’s usage and per-conversation consumption statistics. Maintained by MeteorNOX, it is licensed under MIT, with the current package version at 0.2.10.

It directly addresses a key pain point: no need to repeatedly open the DeepSeek platform to check your balance, nor rely on guesswork to estimate how many tokens you’ve burned today. The information is embedded within the DSH interface, visible alongside your development workflow.

It should be noted that community plugin directories like SkillHub are community-maintained and have no official affiliation with DeepSeek or High-Flyer. Before installing, it’s recommended to review the source code and license yourself, as plugins run with the current dsh process permissions.

Core Features and Highlights

According to the official README, the widget’s main capabilities are as follows:

  1. Auto-launch on Startup: As a standard DSH bundle plugin, it appears as soon as the web interface opens, requiring no manual loading each time.
  2. Balance Monitoring: Auto-refreshes every 60 seconds; clicking the whale manually refreshes; balance changes feature a scrolling number animation; short-term network jitter reuses the last known balance to avoid interface error spam.
  3. Today’s Usage (Two Modes):
    - Whale Bookkeeping (Default, Recommended): Requires only DEEPSEEK_API_KEY, locally tracks usage by observing balance differences (.dshw-usage.json), automatically zeros out and archives daily, eliminating the need for platform session tokens.
    - Real-time Token (Optional): After configuring DEEPSEEK_PLATFORM_TOKEN, calls the platform usage API, converting today’s usage based on peak-valley pricing (weekends are fully off-peak from 2026-08-23 onwards).
  4. Per-conversation Consumption: Listens to local session events, displaying the consumption amount after each conversation ends (based on real usage, not estimates); can be toggled in the menu, with customizable auto-close seconds.
  5. Interaction and Visuals: Supports dragging and snapping to four edges or four quarters; snaps left and flips horizontally; features a bouncy doll effect when pressed; hover over the hamburger menu in the top-right to adjust size (0.6–2.5x), sound effects, volume, usage mode, etc.
  6. Random Lines and Sound Effects: Click the speech bubble to switch between random line segments (including peak-valley tips, cute banter, etc.), auto-collapsing after 5 seconds; press/release to optionally play a duck quack or sound pack (silently degrades if mp3 is missing).

Installation and Enabling

No local cloning needed, just one command:

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

Notes:

  • After successful installation, the plugin will appear in the DSH Plugin Management Page, where you can update it later without repeating the command.
  • If a proxy is needed for the network, set the environment variable before executing the installation command.
  • After installation, restart dsh web and refresh the browser with F5.

Execute in the repository root directory (where package.json is located):

dsh plugin --profile web add link:.

Note: The repository root directory itself is the plugin package. Do not write it as link:.\dsh-whale-widget (this subdirectory does not exist, which would cause it to be installed as a regular dependency rather than a plugin).

Method C: Install After npm Publishing

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

Uninstallation

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

Configuration and Typical Usage

Required Credentials

Configure DEEPSEEK_API_KEY in the DSH credential service (required for pulling api.deepseek.com/user/balance). If not configured, the balance area will indicate that the key is missing.

DEEPSEEK_PLATFORM_TOKEN is optional: If not configured, “Today’s Usage” automatically defaults to the “Whale Bookkeeping” mode, ready to use out of the box.

Usage Mode Selection

Switch in the widget’s hamburger menu → Usage:

  • Whale Bookkeeping: Zero additional configuration, ledger written to $DSH_HOME/.dshw-usage.json, with archives retained for about 30 days. If consumption occurs while DSH is closed, it may be missed; for precise tracking, switch to token mode.
  • Real-time Token: Requires logging into platform.deepseek.com in the browser, copying the Authorization value from the usage/by_api_key/amount request in the developer tools Network tab, configuring it as DEEPSEEK_PLATFORM_TOKEN, and restarting dsh web before selecting this mode.

Verify Successful Installation

dsh --profile web --dump-config | Select-String -Pattern "whale"

curl http://127.0.0.1:3080/dsh-whale/balance.json
curl http://127.0.0.1:3080/dsh-whale/widget.js

Expected: dsh-whale-widget should be visible in the dump-config output; balance.json should return 200 and contain totalBalance; after refreshing the browser, the whale widget should appear in the bottom-right corner.

Per-conversation Consumption

This feature directly listens to DSH local session events, converting amounts based on the model’s real usage and built-in peak-valley pricing table, and does not require DEEPSEEK_PLATFORM_TOKEN. Check “Automatically display consumption after each conversation” in the menu; a conversation must fully complete (turn/end) before settlement and display.

Suitable Scenarios and Considerations

Who Is It For:

  • Developers who regularly use the DSH web interface for developing and debugging agents;
  • Users who need to monitor DeepSeek API balance at all times to avoid sudden service interruptions;
  • Usage-sensitive teams that want to see “how much spent today” and “how much this conversation cost” on the same screen.

Considerations:

  1. Permissions and Security: The plugin runs in the same process as DSH and will read your configured API key. Before installing, please review the source code and MIT license to ensure it aligns with your security policies.
  2. Platform Token Validity: DEEPSEEK_PLATFORM_TOKEN comes from the platform web session and may need to be re-obtained after re-logging in.
  3. Pricing Table Maintenance: Peak-valley pricing is written in the PRICING constant in lib/index.js; you need to follow up and update it yourself if DeepSeek adjusts prices.
  4. Common Issues: Widget not appearing → Confirm dsh plugin add succeeded, dump-config includes dsh-whale-widget, dsh web restarted, and browser refreshed; today’s usage shows -- → Bookkeeping mode requires an initial balance observation (automatically within 60 seconds); no sound → Check if assets/*.mp3 is in the package, or accept silent degradation.

Conclusion

If you’ve been immersed in DSH for a long time but still find yourself switching out to check your balance, this little whale-girl in the bottom-right corner is worth a try: the installation command is simple, the default bookkeeping mode requires almost zero configuration, and the interaction details (dragging/snapping, bouncing, scrolling numbers) make “monitoring your balance” less tedious.