Introduction

When running a web session with DeepSeek Harness (DSH), switching between different providers often requires checking the balance or subscription usage on the corresponding vendor’s page. dsh-balance is a DSH web plugin maintained by GeekRicardo, under the MIT license. It displays the current provider’s balance/usage in the status bar below the input box and switches in real-time per provider, reducing manual queries.

What is it

dsh-balance is a DSH web plugin. Its core capabilities are:

  • Displaying the current provider’s balance/usage in the status bar below the input box;
  • Real-time switching based on the current provider;
  • 2-second polling update;
  • 5-minute cache for balance/usage;
  • Prioritizing cached display to prevent blank screens when switching sessions.

The plugin reads corresponding provider keys from ~/.dsh/.credentials.yaml. The Host registers an HTTP route /dsh-balance/status, and the Client polls this route and renders the status. It determines the current provider using agentDefaultModel.currentSelection().

package.json declares react as an optional peerDependency, requiring version ^18.2.0.

Supported Providers

Below is the current support list. Other providers are not displayed and return null.

provider Display Content Key Interface
deepseek / deepseek-official / deepseek-vision DeepSeek official balance + estimated session cost DEEPSEEK_API_KEY GET api.deepseek.com/user/balance
kimi-coding Kimi Coding subscription usage KIMI_CODING_API_KEY, compatible with KIMI_CODE_API_KEY / KIMI_API_KEY GET api.kimi.com/coding/v1/usages
opencode-go OpenCode Go subscription usage OPENCODE_GO_API_KEY, compatible with OPENCODE_API_KEY GET opencode.ai/zen/go/v1/usage
zai-coding-cn / zai Zhipu GLM Coding Plan subscription usage ZAI_CODING_CN_API_KEY / ZAI_API_KEY GET open.bigmodel.cn or api.z.ai/api/monitor/usage/quota/limit
minimax-cn / minimax MiniMax Coding Plan subscription usage MINIMAX_CN_API_KEY / MINIMAX_API_KEY GET api.minimaxi.com or api.minimax.io/v1/api/openplatform/coding_plan/remains
openrouter OpenRouter balance OPENROUTER_API_KEY GET openrouter.ai/api/v1/credits
openai-codex OpenAI Codex subscription usage OPENAI_CODEX_ACCESS_TOKEN, optional OPENAI_CODEX_ACCOUNT_ID GET chatgpt.com/backend-api/wham/usage

Real-time & Caching

The following points determine the update rhythm of the status bar:

  1. The Client polls /dsh-balance/status every 2 seconds; therefore, after switching models or conversations, the status bar updates at most every 2 seconds.
  2. The Host caches balance/usage by provider, re-querying once every 5 minutes under the same provider.
  3. The Client caches the last successful reading in memory and localStorage. When switching sessions or refreshing the page, it renders the cache first, then requests the latest data in the background.
  4. Cross-session caching resets DeepSeek “session cost” to zero, but balance/usage is displayed as usual.
  5. Determination of the current provider relies on agentDefaultModel.currentSelection(), not on the model of the most recent request.

Installation & Enabling

Prerequisites

Before installation, ensure the following:

  • DeepSeek Harness web profile has been initialized, i.e., ~/.dsh/profiles/web exists;
  • Node.js >= 20 is available;
  • pnpm is available;
  • Corresponding provider keys are configured in ~/.dsh/.credentials.yaml.

Official Installation Command

Here is a command to install:

curl -fsSL https://raw.githubusercontent.com/GeekRicardo/dsh-balance/main/install.sh | bash

The installation script can be previewed with --dry-run first.

The script will do the following:

  1. Write dependency "dsh-balance": "github:GeekRicardo/dsh-balance" to ~/.dsh/profiles/web/package.json;
  2. Append dsh-balance to dsh.profile.bundles;
  3. Execute cd ~/.dsh/profiles/web && pnpm install;
  4. Verify bundles are registered and prompt to restart DSH.

Restart DSH

If hosted with pm2, you can run:

pm2 restart dsh-web

Otherwise, restart DSH using your original method.

After restarting, perform a hard refresh of the page for the status bar to take effect.

Typical Usage

  1. Configure corresponding provider keys in ~/.dsh/.credentials.yaml.
  2. Install the plugin and restart DSH.
  3. Switch providers, models, or conversations on the DSH web page.
  4. Observe the status bar below the input box:
    • After switching models/conversations, the status bar updates at most every 2 seconds;
    • Balance/usage is re-queried every 5 minutes under the same provider;
    • DeepSeek session cost is accumulated separately per session;
    • DeepSeek session cost starts accumulating after the plugin loads and resets on restart, not persisted.

Billing & Usage Scope

DeepSeek

The DeepSeek official API does not return monetary amounts, only token counts. The amounts in the plugin are an estimate of token count × unit price, not the actual bill.

The unit price comes from models.dev, calculated in USD/1 million tokens, matching based on the model prefix. Falls back to built-in unit prices if fetching fails. The exchange rate is fixed at 7.2.

Kimi Coding

Kimi Coding usage is only displayed when the provider is kimi-coding, i.e., api.kimi.com/coding.

OpenCode Go

OpenCode Go usage is only displayed when the provider is opencode-go, i.e., opencode.ai/zen/go.

This interface requires both of the following request headers:

Authorization: Bearer <token>
x-api-key <key>

Uninstallation

When uninstalling, follow these steps:

# 1. Remove "dsh-balance" from dsh.profile.bundles in ~/.dsh/profiles/web/package.json
# 2. Remove "dsh-balance" from dependencies
# 3. cd ~/.dsh/profiles/web && pnpm install
# 4. Restart DSH

Troubleshooting

Phenomenon Cause & Resolution
Nothing displays below input box Current provider not in support list, or Host hasn’t loaded; check provider list and restart DSH
Displays “Balance unavailable” Corresponding provider key not configured, or interface authentication failed; check if the corresponding key exists and is valid in ~/.dsh/.credentials.yaml
Reading doesn’t change immediately after switching models Polling interval is 2 seconds; if it still doesn’t update, confirm current selection is saved and currentSelection() is effective
Balance number never changes Balance/usage is re-queried every 5 minutes under the same provider; this is expected cache behavior

Security Tips

dsh-balance runs with the permissions of the current DSH process and reads provider keys from ~/.dsh/.credentials.yaml. Before installing, it is recommended to check the source code and MIT license to confirm the source is trustworthy.

  • GitHub: https://github.com/GeekRicardo/dsh-balance
  • Directory: https://www.skillhub.cn/plugins/GeekRicardo/dsh-balance (from plugin link, marked as uncertain in fact verification)