Foreword¶

When running agent tasks with DSH (DeepSeek Harness), API balance and spending usually require opening the official console separately: switching pages, logging in, and reviewing invoices, which can interrupt the task at hand. If you want to quickly check “how much balance remains and how much has been spent on recent days,” a persistent monitor inside the client is needed.

The dsh-deepseek-balance plugin introduced below addresses this problem: it places a floating badge in the bottom-right corner of the window, displays the account balance in real time, and adds 7-day / 30-day usage cost charts.

What Is This¶

dsh-deepseek-balance is a DSH plugin maintained by lin-cheng-lab. Its current version is 0.1.0, and the license is MIT. In one sentence: a DeepSeek API balance monitor—a floating badge in the bottom-right corner of DSH + 7-day/30-day usage cost charts.

DSH’s philosophy is “everything is a plugin,” and this plugin makes “checking the balance” part of the client UI. The data comes from two sources: the balance is fetched from the official endpoint GET https://api.deepseek.com/user/balance; usage is counted from actual token usage in local DSH session logs and converted into costs using the official pricing.

Core Features¶

According to the README, the plugin provides the following capabilities:

A persistent bottom-right floating badge: a status-colored dot + real-time balance, visible on any page/session;
A usage cost chart: 7-day / 30-day bar chart, with daily amounts available on hover;
Automatic refresh every 60 seconds, with manual refresh also available;
Automatic light/dark theme adaptation (using DSH theme variables);
Automatically reads the configured DEEPSEEK_API_KEY credential, without requiring manual entry;
Key security: the key is passed to curl via an environment variable, so it does not appear in plaintext in the command line or logs.

Installation and Enablement¶

First install the plugin. The command below is from the README; replace the <your username> placeholder with the actual repository path:

dsh plugin --profile web add "github:<你的用户名>/dsh-deepseek-balance#main"

Then configure the credential. Write the following to ~/.dsh/.credentials.yaml:

DEEPSEEK_API_KEY: sk-xxxxxxxxxxxxxxxxxxxxxxxx

After these steps, restart dsh --profile web, and the balance badge should appear in the bottom-right corner. The plugin will read this credential automatically, so you do not need to enter the key manually in the interface.

Note: the plugin’s Client platform is web, so it must be run with dsh --profile web.

How It Works¶

The plugin has two parts: a Host (Node process) and a Browser UI. The Browser UI is mounted on shell.overlay and is responsible for the floating badge and charts. For queries, it calls /deepseek-balance through connection.rpc.call, and the Host performs three things:

credentials.resolve resolves the credentials;
It invokes curl through a shell to request the balance API, passing the key via an environment variable so it does not appear in the command line or logs;
sessionQuery aggregates local session log token usage and converts it into costs.

The structure diagram in the README is as follows:

┌──────────────┐   connection.rpc.call   ┌──────────────────────────┐
│  Browser UI  │ ──────────────────────▶ │  Host (Node)             │
│  shell.overlay│  /deepseek-balance      │  ├─ credentials.resolve  │
│  悬浮徽章+图表 │ ◀────────────────────── │  ├─ shell curl 余额 API  │
└──────────────┘   RpcResult             │  └─ sessionQuery 用量统计 │
                                         └──────────────────────────┘

It should be noted that the usage chart is based on token statistics from local DSH session logs. Older history without local records is shown as gray placeholder bars.

Local Development and Build¶

If you want to modify the code or build from source, Node >= 22.19.0 is required (the engines field in package.json). First install dependencies, then build:

pnpm install
pnpm build    # tsc 编译 Host + tsdown 打包 Client

Build artifacts are lib/index.js (Host half, RPC handlers: balance/usage query) and lib/client.js (Client half, floating badge UI).

Use Cases and Cautions¶

Suitable scenarios:

Long-term use of the DeepSeek API inside DSH, with a need to keep track of the balance at any time;
Care about daily spending trends and want to review usage with 7-day / 30-day charts;
Do not want to hand the API key to a third-party dashboard, and prefer to keep the key only in a local credential file.

A few cautions:

The plugin runs with the permissions of the current dsh process, and can read local credentials and session logs. Before installing, it is advisable to review the source code and license (this project is MIT);
It must be started with dsh --profile web; otherwise, the Client will not take effect;
The balance query relies on the Host calling the official API through curl, passing the key via an environment variable, so it will not appear in the command line or logs.

Conclusion¶

In summary: dsh-deepseek-balance brings DeepSeek’s balance and usage information to the bottom-right corner of the DSH client. The balance comes from the official API, usage comes from actual local session log statistics, and the key remains local throughout. For developers who work with the DeepSeek API every day, this is a small but practical add-on.

Project address:

GitHub: https://github.com/lin-cheng-lab/dsh-deepseek-balance
Community directory page: https://www.skillhub.cn/plugins/lin-cheng-lab/dsh-deepseek-balance

(The directory is an independent community site and has no official affiliation with DeepSeek / High-Flyer.)

dsh-deepseek-balance: Real-time view of DeepSeek API balance and usage fees at the bottom right of DSH