What mode does the DSH whale widget use by default for today's usage? Does it need a token?

The DSH whale widget uses whale bookkeeping mode by default, which needs no token and records locally via balance difference with cross-day archiving. Only DEEPSEEK_API_KEY is required to fetch the balance; for more precise real-time usage, configure DEEPSEEK_PLATFORM_TOKEN and switch to real-time token mode.

How do I manually refresh the DSH whale widget balance in DeepSeek Harness, and how often does it auto-refresh?

The DSH whale widget refreshes manually when you click the whale bubble and auto-refreshes every 60 seconds by default, with a rolling number animation on change. On network jitter it silently falls back to the latest balance instead of erroring.

What credential does the real-time token mode need, and where do I get it?

The DSH whale widget's real-time token mode needs DEEPSEEK_PLATFORM_TOKEN, a session token for the DeepSeek platform website — not an sk- prefixed API key. Copy the Authorization header from the platform usage API request, configure it as a DSH credential, and restart.

How do I verify the DSH whale widget is working after installation?

After installing the DSH whale widget, restart dsh web and refresh the browser — the whale should appear in the bottom-right corner. Run dsh --profile web --dump-config to check that bundles includes dsh-whale-widget.

Why does today's usage show -- in the DSH whale widget, and how do I fix it?

Today's usage shows -- in the DSH whale widget when the first balance observation hasn't run yet in bookkeeping mode — it completes within 60 seconds; in token mode you must configure DEEPSEEK_PLATFORM_TOKEN first. If it still doesn't show, check that DEEPSEEK_API_KEY is set.

What special effect does the DSH whale widget have when snapped to the left edge?

When you drag the DSH whale widget to the left edge, the whole widget flips horizontally with reversed text and an animation, plus a squishy effect while pressed. It snaps to all four edges and corners and scales automatically with the browser window.

What Is deepseek-balance-whale-widget? Whale Widget for DSH

deepseek-balance-whale-widget (the DSH Whale Balance Widget) is a DeepSeek Harness (DSH) UI plugin that keeps a whale bubble chart in the bottom-right corner of the web UI, showing DeepSeek API balance, today's usage, and per-conversation cost in real time.

The DSH Whale Balance Widget solves the hassle of manually checking your balance and estimating usage: balance, today's usage, and per-turn cost are shown directly inside the DSH interface.

The DSH Whale Balance Widget (deepseek-balance-whale-widget, GitHub repo meteornox/deepseek-balance-whale-widget) is maintained by meteornox under the MIT license. Previously you had to leave DSH and open the DeepSeek console to see account consumption; with the widget installed, balance, today's usage, and per-turn cost are all displayed right inside the interface. It appears automatically every time the DSH Web UI opens (a standard DSH bundle plugin), and only requires configuring DEEPSEEK_API_KEY to fetch the balance — an out-of-the-box UI plugin in the DSH Plugin ecosystem (source).

The core capabilities of the DSH Whale Balance Widget revolve around "seeing how much you have spent at a glance": real-time balance, dual daily-usage modes, per-conversation cost stats, plus drag-and-drop snapping and customizable sounds and lines. These capabilities all come from the official README (source):

Auto-start: it appears automatically every time the DSH Web UI opens, with no manual launch needed.
Real-time balance: auto-refreshes every 60 seconds, manual refresh on click, rolling number animation on change, and falls back to the latest balance on network jitter without errors.
Dual daily usage modes: whale bookkeeping mode needs no token and records locally via balance difference with cross-day archiving; real-time token mode calls the platform usage API and converts using peak/off-peak pricing.
Per-conversation cost stats: listens to local session events and pops up the exact cost after each round, toggleable with custom auto-close seconds.
Drag-and-drop snapping and mirror flip: snaps to four edges and corners, flips horizontally when snapped left, with a squishy toy effect on press.
Hamburger menu customization: adjust size (0.6–2.5x), switch sounds and volume, choose the usage mode, and toggle bubbles and per-round cost hints.

Installing the DSH Whale Balance Widget in DeepSeek Harness takes one official plugin command; after installation, restart dsh web and refresh the browser to see the whale in the bottom-right corner.

1. Install the DSH Whale Widget: run the install command in the DSH terminal to add the plugin to the current profile:

bash

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

Wait for the install to finish; the plugin then appears in DSH's plugin management page, where you can update it directly. You can also install from the GitHub source:

bash

dsh plugin --profile web add github:meteornox/deepseek-balance-whale-widget

2. Enable and confirm it works: after installation, restart dsh web and refresh the browser; the whale bubble should appear in the bottom-right corner. Use the config dump command to confirm the plugin is loaded:

bash

dsh --profile web --dump-config

The bundles in the output should include dsh-whale-widget; you can also open http://127.0.0.1:3080/dsh-whale/balance.json to confirm a JSON response with totalBalance.

3. Update the plugin: re-run the update command when you need a newer version:

bash

dsh plugin --profile web update dsh-whale-widget

4. Uninstall the plugin: remove it when no longer needed:

bash

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

The command forms above follow the host documentation, and the target name dsh-whale-widget comes from the README and the plugin entry (source).

The DSH Whale Balance Widget works right after installation; daily actions are mainly configuring credentials, choosing a usage mode, tweaking the menu, and verifying the widget.

1. Configure DEEPSEEK_API_KEY (required): set the DeepSeek API key in DSH's credential service; it fetches the balance from api.deepseek.com/user/balance:

bash

# e.g. edit ~/.dsh/.credentials.yaml
# DEEPSEEK_API_KEY: <your DeepSeek API key>

Once set, the widget fetches the balance automatically and uses bookkeeping mode for today's usage by default.

2. Choose a daily usage mode: pick one in the "Usage" section of the hamburger menu. The default whale bookkeeping mode needs no token and works out of the box; for precise hourly real-time usage, configure DEEPSEEK_PLATFORM_TOKEN (the DeepSeek platform web session token) and switch to real-time token mode:

bash

# DEEPSEEK_PLATFORM_TOKEN: <Bearer eyJ... platform web session token>

This token is not an sk- prefixed API key and may expire after you log back into the platform web page.

3. Personalize the widget: hover over the whale's top-right corner to open the hamburger menu — adjust size (0.6–2.5x), switch sounds (duck/sound1) and volume, choose the peak/off-peak hint text, and toggle bubbles and per-round cost hints; click the bubble to cycle random lines, and click again to close.

4. Verify the widget works: confirm the whale appears in the bottom-right corner and check the balance endpoint:

bash

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

It should return JSON with totalBalance and todayUsage (source).

If the DSH Whale Balance Widget has issues such as "widget does not appear" or "today's usage shows --", start by matching the symptoms below.

1. The whale does not appear: the symptom is no whale in the bottom-right corner after a restart and refresh. The cause is an unsuccessful install or DSH not loading the bundle. Fix: run dsh --profile web --dump-config to confirm dsh-whale-widget is in bundles, restart dsh web, then refresh the browser with F5.

2. Today's usage shows --: the symptom is a placeholder in the usage area while the balance looks fine. In bookkeeping mode the first balance observation hasn't run yet — it completes within 60 seconds automatically; in real-time token mode you must configure DEEPSEEK_PLATFORM_TOKEN first.

3. "DEEPSEEK_API_KEY not configured": the symptom is a missing-key message in the balance area. The cause is a missing credential. Fix: configure DEEPSEEK_API_KEY in DSH's credential service and restart; the balance then loads normally.

4. Per-round cost does not show: the symptom is no cost bubble after a conversation ends. The cause is the "auto-show cost after each round" toggle being off, or the round not finishing completely. Fix: enable the toggle in the hamburger menu and make sure the round ends fully (turn/end) before settlement (source).

Use Cases and Notes

The DSH Whale Balance Widget suits every DeepSeek user who wants to see account consumption inside DSH at any time, especially those who need to control costs and check per-round spending.

Use cases: developers who use the DeepSeek API heavily and need to manage budgets; users who want to know exactly how much a conversation cost the moment it ends; and people who like lightweight, visual UI tools. The widget scales automatically with the browser window, with text position and font size tied to the image.

Notes: the default bookkeeping mode relies on observing balance decreases, so usage during DSH downtime is missed — use real-time token mode when precision matters; the platform session token may expire after you log back into the platform website; if you move the local source directory, re-run the install command and restart; missing audio files degrade silently to no sound without affecting functionality (source).

Project Links

The DSH Whale Balance Widget is an MIT open-source project maintained by meteornox. Plugin detail page: DSH Whale Widget plugin details.

This page is an independent guide rewritten from the plugin's official README — for the authoritative documentation and the latest changes, defer to the source: meteornox/deepseek-balance-whale-widget. A plugin is third-party code that runs on your machine once installed; inclusion is not an endorsement — review the source before installing.

What Is deepseek-balance-whale-widget? Whale Widget for DSH

What Is deepseek-balance-whale-widget?

What Are the Core Features of deepseek-balance-whale-widget?

How to Install and Enable deepseek-balance-whale-widget?

Typical deepseek-balance-whale-widget Usage

deepseek-balance-whale-widget Troubleshooting

Use Cases and Notes

Project Links

FAQ

Related Terms

Sources