DSH plugin balance whale widget: live DeepSeek Harness usage

The DSH plugin balance whale widget is the community plugin DeepSeek Balance Whale Widget: a small whale in the corner of the DeepSeek Harness Web UI that shows your DeepSeek account balance, today's spend and per-turn cost (source). It is a standard DSH plugin bundle installed with dsh plugin, and it needs no extra session token. To compare balance and usage plugins, filter the market on DSH Plugin Hub.

What the DSH plugin balance whale widget does

It is a small panel that keeps three numbers where you can always see them: account balance, today's spend and per-turn cost (source). Concretely:

1. Shows the balance. It refreshes every 60 seconds and can be refreshed by clicking the whale; the digits roll when the number changes.
2. Tracks today's spend. It accumulates the day's consumption from balance observations with no extra token, and records top-ups or credits that raise the balance separately.
3. Reports per-turn cost. It listens to local session events, converts the model's real usage into money, and pops a cost note when a turn ends (closable and customisable).

It appears automatically each time the Web UI opens, so it is a display panel for money left rather than a tool you must launch.

The three numbers on the panel, and where each one comes from

The three numbers are not three views of one fetch — one is fetched and two are computed locally (source).

That split explains the two most common surprises: if the balance itself is right but today's spend looks off, the fetch is fine and the local bookkeeping is what to check; and a top-up raises the balance without being counted as negative spend, because credits are recorded separately.

Where the balance comes from: two data paths

The widget prefers a configured API key and falls back to the account login state, so you normally configure nothing extra (source).

Two consequences worth knowing: both paths can read the same account, so a key and a login do not stack into two balances; and if neither path is usable, the widget simply has nothing to show — which is the first thing to check when the panel is blank.

How to install the DSH plugin: command, profile and where balance data comes from

Install the balance whale widget with dsh plugin --profile web add dsh-whale-widget, using the web profile (source). Three steps in order:

1. Pick one source and stay with it. Installing the published npm release is recommended: dsh plugin --profile web add dsh-whale-widget. You can also install from the repo: dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget, but that pins the repository's current state instead of following published releases. Expected: dsh plugin --profile web list shows dsh-whale-widget.
2. Avoid a coexist conflict. The npm name and the github: form point at the same package, so installing one after the other leaves both present and conflicting; if you installed via github: and want the npm name, run dsh plugin --profile web remove dsh-whale-widget first. Expected: the plugin appears once in list, with no npm-name and github: duplicate.
3. Confirm the profile. The widget belongs to the Web UI, so use --profile web. The official desktop app reads its own desktop profile and the CLI refuses --profile desktop, so install there by another route. Expected: it shows under --profile web, while --profile desktop is refused by the CLI.

Where the balance comes from: it prefers DEEPSEEK_API_KEY from the DeepSeek Harness credentials, and if you are signed in to a DeepSeek account without a key it uses the DeepSeek Harness account login state instead, so you normally configure nothing extra. You do not need to create a key after installing; the widget fetches data on its own.

When the DSH plugin balance whale widget shows no balance, and how it differs from cost plugins

If no balance appears, check credentials, then network, then refresh by hand; and remember it reads a different number than a cost or usage plugin (source). The self-check:

1. Credentials. Confirm DEEPSEEK_API_KEY in the DeepSeek Harness credentials is usable, or that you are signed in and the balance entry can be read.
2. Network. Confirm the environment can reach the DeepSeek endpoint; during a brief wobble the widget keeps the last known balance without error, so a short gap is usually normal.
3. Manual refresh. Click the whale to force a refresh and watch whether the number moves; if it still does not, go back to the first two steps.

The difference from cost and usage plugins, dimension by dimension:

If you want both readings, install one of each.

Verifying the DSH plugin balance whale widget after install

Check the profile and the loaded bundles, not just the absence of an error.

# 1) Did the widget land in the web profile?
dsh plugin --profile web list
# "dsh-whale-widget" should be listed exactly once

# 2) Does the profile load it as a bundle?
grep -A5 "bundles" "$DSH_HOME/profiles/web/package.json"
# the widget should appear among the loaded bundles

Expected: exactly one entry in the listing and one bundle reference. If the listing shows the widget twice, you installed both the npm name and the github: form — remove one. If it is listed but not loaded as a bundle, restart the profile's process before debugging the widget itself.

Notes on the DSH plugin balance whale widget

Treat it as a resident panel that only shows the balance, get the profile and source right, and there is little to trip over.

1. Use the web profile: it belongs to the Web UI, so install with --profile web.
2. One source only: the npm name and github: are the same package — do not install both in sequence.
3. No extra token: it reads the DeepSeek Harness credential or the account login state.
4. Not updating is not necessarily broken: during a network wobble it keeps the last balance without error.
5. Desktop takes another route: the CLI refuses --profile desktop, so do not copy the Web command there.
6. Mind the readings: it shows balance; cost detail comes from a cost or usage plugin.
7. Find similar plugins on DSH Plugin Hub; the easily confused whale pet widget is in whale pet widget install.

Common misconceptions about the DSH plugin balance whale widget

Five assumptions that cause wrong troubleshooting:

1. "All three numbers come from one fetch." No — the balance is fetched, while today's spend and per-turn cost are computed locally.
2. "I must create an API key before it works." No — signing in is enough if no key is configured.
3. "A key plus a login doubles the balance." No — both paths read the same account.
4. "A blank panel always means a network fault." No — a missing credential or login state produces the same blank panel.
5. "It also tells me where the spend went." No — it shows money left; per-turn and per-model detail is a cost or usage plugin's job.

Source: Community plugin repo - DeepSeek Balance Whale Widget, DeepSeek Harness CLI README.