dsh-balance

English | 中文

A DeepSeek Harness plugin that puts the account balance of the provider serving your active model in the sidebar foot — right-aligned next to the Settings button — and keeps it fresh.

The chip is provider-aware: it reads the active session's selected model and shows the matching provider's balance, flipping automatically when you switch models.

On DeepSeek the chip also tracks peak / off-peak billing — the status dot turns red inside DeepSeek's peak window and green off-peak, when requests cost half price. See DeepSeek peak / off-peak hours.

Contents

• Why dsh-balance?
• Lightweight by design
• Highlights
• Screenshots
• Supported providers
  • DeepSeek peak / off-peak hours
• Install
• Configuration
• Preview without an account (mock mode)
• How it works
• Development
• Troubleshooting
• FAQ
• Changelog
• License

Why dsh-balance?

• Provider-aware, not DeepSeek-only. It follows the active model's provider across DeepSeek, OpenRouter, Moonshot/Kimi, Zhipu/GLM, and MiniMax — the chip changes the moment you switch models.
• The smallest thing that does the job. No settings panel, no cost projection, no extra services. One route, one chip, ~11 kB gzipped.
• Zero core interference. An out-of-tree package that registers into a declared slot. Nothing in the Harness source is patched or forked.

Lightweight by design

dsh-balance is deliberately minimal, and it adds no machinery to the Harness:

Nothing to configure, nothing to tear down. Install it and the only change is one row in the sidebar foot. Uninstall it and the Harness is exactly as it was.

Highlights

• One chip, five providers. DeepSeek, OpenRouter, Moonshot/Kimi, Zhipu/GLM (Z.ai), and MiniMax — each with its own brand mark, currency, and tooltip breakdown.
• Provider-aware. Switching the active model switches the chip to that provider's balance immediately.
• Peak/off-peak aware on DeepSeek. The status dot turns red during DeepSeek's peak billing window (Monday–Friday, Beijing 09:00–12:00 and 14:00–18:00) and green off-peak, when requests cost half price.
• Your key never reaches the browser. The host half resolves the credential and calls the provider; the browser only ever sees a normalized balance.
• Live. Auto-refreshes every 60 seconds, on click, when the session changes, and the moment the model's provider changes.
• Graceful. A missing key or an upstream error becomes a muted Balance — pill with the reason in the tooltip — never a broken layout.
• Preview without an account. A built-in mock mode renders real-looking balances for any provider.

Screenshots

Light theme	Dark theme

Supported providers

The mapping is deliberately narrow: a route the plugin does not recognize (including a custom provider id) falls back to the DeepSeek balance rather than failing the chip.

What the chip shows

• [brand mark] $9.74 ● — the provider's logo, the amount, then a status dot.
• Status dot — DeepSeek marks its peak/off-peak billing window (green = off-peak, red = peak; see DeepSeek peak / off-peak hours). OpenRouter, Moonshot, Zhipu, and MiniMax mark a positive remaining balance or quota (green = left, red = exhausted).
• Tooltip — the full breakdown (for example Total $42.50 · Granted $5.00 · Topped up $37.50).
• Click — refresh now.
• Errors — a muted Balance — pill; hover for the reason, click to retry.
• The collapsed 56px sidebar rail hides the chip — there is no room beside the gear.

DeepSeek peak / off-peak hours

DeepSeek bills off-peak requests at half the peak price. The chip's status dot reflects the current window, evaluated in UTC so it is correct regardless of your machine's timezone:

Source: DeepSeek API — Models & Pricing, footnote (1): "Off-peak prices are half of the peak prices. Peak hours are Beijing time Monday to Friday 9:00–12:00 and 14:00–18:00 (all other times are off-peak)."

DeepSeek is the only one of the five with a recurring peak/off-peak schedule. The other providers have no time-of-day pricing windows, so their dot reflects balance/quota rather than a pricing window:

Install

Requirements: a DeepSeek Harness install with the web profile (dsh web) and Node.js ≥ 22.18.

The plugin is self-contained: it needs no extra services, no configuration file, and no core patch. Installation adds one dependency and one sidebar row.

From npm

pnpm dsh plugin --profile web add @andrecgoncalves/dsh-balance

From GitHub

pnpm dsh plugin --profile web add github:andregoncalves/dsh-balance

The package builds itself on install (prepare → pnpm run build), so lib/ does not need to be committed.

From a local clone (development)

git clone https://github.com/andregoncalves/dsh-balance.git
cd dsh-balance
pnpm install
pnpm run build
pnpm dsh plugin --profile web add link:"$PWD"

Use link: rather than file:: a plain file: dependency is hardlinked and breaks on atomic rebuilds.

How the row is wired

The package declares dsh.bundle, so dsh plugin add appends it to your profile's dsh.profile.bundles and the bundle's own cordis.patch.yml inserts the sidebar row — no manual patch editing. Refresh the browser once after the first install so the boot manifest (window.__DSH_BOOT__) picks up the new row; after that, source changes rebuild and hot-swap live.

"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@andrecgoncalves/dsh-balance"] } }

- insert:
    - id: dsh-balance
      name: "@andrecgoncalves/dsh-balance"

Verify

curl http://127.0.0.1:3080/plugins/balance                    # DeepSeek
curl "http://127.0.0.1:3080/plugins/balance?kind=openrouter"  # OpenRouter
curl "http://127.0.0.1:3080/plugins/balance?kind=moonshot"    # Moonshot / Kimi
curl "http://127.0.0.1:3080/plugins/balance?kind=zhipu"       # Zhipu / GLM
curl "http://127.0.0.1:3080/plugins/balance?kind=minimax"     # MiniMax

Each returns {"ok":true,"provider":"…","balance":{…}}, or {"ok":false,"error":"no-key","message":"…"} when the credential is missing.

Configuration

DeepSeek resolves DEEPSEEK_API_KEY through the Harness credentials seam (for example ~/.dsh/.credentials.yaml). The other providers try the seam first, then fall back to the ambient launch environment (process, the invoking project's .env, then the Harness home's .env).

To share one credential plane with the model adapter, store the key in ~/.dsh/.credentials.yaml and add apiKeyEnv to the route. Zhipu's account endpoints expect the key verbatim (no Bearer prefix); the host applies the right scheme automatically. Moonshot and Zhipu mirror across two regional hosts, so a key valid on only one site falls through to the other before the request is reported as failed.

Preview without an account (mock mode)

Mock mode serves canned balances from the host and skips credential resolution and the upstream call. It is off by default and enabled with DSH_BALANCE_MOCK=1 or a ?mock=1 query parameter.

curl "http://127.0.0.1:3080/plugins/balance?kind=moonshot&mock=1"
curl "http://127.0.0.1:3080/plugins/balance?kind=zhipu&mock=1"
curl "http://127.0.0.1:3080/plugins/balance?kind=minimax&mock=1"

To see it in the GUI, start the server with the environment variable:

DSH_BALANCE_MOCK=1 dsh web

Then add a route in Settings → Models for the provider you want to preview (moonshotai, zai, minimax, …), add a model, and select it. The chip follows the active model and shows the canned balance with no real key. Mock mode never reads a credential and never contacts a provider — its numbers are for layout preview only.

How it works

dsh-balance is a dual-face Cordis package: one npm package with a host half and a browser half.

The browser bundle is served by the host's client-module pipeline in the window.__ModuleLoader__.load({ id, factory }) closure format the web shell consumes; react and the @deepseek-ai/* platform modules stay external and resolve from the browser's frozen module table.

Forking note. The client-module entry id is the npm package name. The build reads it from package.json (tsdown.config.ts), and scripts/verify-client.mjs asserts the same value. If you rename the package, update the name in cordis.patch.yml and the entry in the profile's dsh.profile.bundles too — the plugin's internal Cordis name export stays dsh-balance.

Development

pnpm install
pnpm run build     # tsdown: lib/index.js (host) + lib/client.js (browser)
pnpm run verify    # evaluates the client bundle against a stubbed module table

With a link: install, rebuilding lib/ updates the running app immediately, including a live hot-swap of the chip in an open browser tab. Host-side changes may need a reload or restart depending on your DSH workflow.

The @deepseek-ai/* platform packages are optional peer dependencies supplied by the running Harness, so they are never fetched during pnpm install (see pnpm-workspace.yaml). TypeScript type-checking therefore requires a Harness checkout on your tsconfig paths; the build itself has no such requirement.

Troubleshooting

FAQ

Does the browser ever see my API key? No. The host half resolves the credential through the Harness credentials seam and calls the provider; the browser only receives a normalized balance.

Will it break the Harness if I remove it? No. It registers one route and one slot component, both owned by the plugin. Uninstall it and the Harness is exactly as it was — nothing in the core is modified.

What does it cost to run? One small local HTTP request per minute per open tab, and only while the sidebar is wide. Mock mode makes no provider requests at all.

Why does a custom provider show the DeepSeek balance? Unknown routes deliberately fall back to DeepSeek instead of failing the chip. Open an issue with the route id and it can be added.

Does it work with a headless/CLI session? The chip is a web-sidebar feature; the host route works in any profile that mounts the web server, but there is no chip to render without the web UI.

Changelog

See CHANGELOG.md for the full history. Every release is also published on GitHub Releases and npm.

License

MIT © 2026 Andre Goncalves