Preface¶

DeepSeek Harness (dsh) is an open-source agent runtime from DeepSeek, whose official repository sums it up in one sentence: Everything is a Plugin. Models, tools, conversations, and UIs are all assembled via Cordis plugins. Developers can add their own capabilities at the configuration layer without modifying the core source code. It is currently in developer preview, and the official documentation explicitly notes that breaking changes may occur.

A very practical issue encountered when using the Web UI to run agents is: how much DeepSeek API credit remains and how much has been spent today. The official provides the GET /user/balance interface, but the default interface does not display this information in the sidebar. The community plugin dsh-balance-monitor solves this problem: it places the balance, remaining progress bar, and today’s spending at the bottom of the sidebar, above the settings button.

First, we need to clarify the source. The content introduced in this article is from the repository maintained by jelly-000, and its catalog page is on the community site DeepSeek Harness Plugin Repository. This site is an independently operated community directory and has no affiliation or endorsement relationship with DeepSeek / Fang Tian. There are several other balance plugins with similar names, so when installing, please confirm the package source as github:jelly-000/dsh-balance-monitor and do not search only by the package name.

What It Is¶

dsh-balance-monitor is a UI enhancement plugin licensed under MIT, primarily written in JavaScript. The version in package.json is 0.1.2, and it declares dsh.client.platform as web, meaning the widget will only appear in the Web UI and not in the pure terminal session.

The catalog page describes its purpose concisely: Display DeepSeek balance, remaining progress bar, and today’s spending at the bottom of the sidebar. The repository README provides more details: it only uses official design tokens, mounts itself in the official slot sidebar.footer.action, and does not modify core code or perform DOM hacks. The community directory rates it 7 stars; as of the writing of this article, the GitHub repository has 8 stars, was created on 2026-08-13, and the last push was on 2026-08-14.

It solves a single, focused problem: users can check if their account balance is sufficient in the chat interface without opening the platform console.

Core Features¶

Based on the catalog page, README, and repository source code (lib/index.js, lib/client.js), the current capabilities can be divided into the following sections:

Real-time Balance. The server reads the DEEPSEEK_API_KEY (environment variables take priority, otherwise reads from $DSH_HOME/.credentials.yaml, with the default directory being ~/.dsh), and calls the official interface GET https://api.deepseek.com/user/balance. It prioritizes CNY from the returned balance_infos, falls back to the first entry if CNY is unavailable. The interface displays CNY as ¥ and USD as $. The card text has both Chinese and English dictionaries, which follow dsh’s locale settings.
Today’s Spending. Calculated based on the local calendar day. The balance from the first successful query of the day is recorded as the baseline and written to $DSH_HOME/storages/balance-monitor.json, allowing the data to persist across page refreshes or process restarts. The spending calculation in the source code only accumulates decreases in balance: recharging will not turn today’s spending negative or erase already recorded spending; if the balance is higher than the daily baseline due to a recharge, the baseline will be raised accordingly, and the progress bar will refill fully. The baseline and spending will reset when the day changes or the currency is switched. The README’s simplified description spending = max(0, baseline − current) follows the same logic.
Remaining Progress Bar. The ratio is calculated as current balance ÷ daily baseline, clamped between 0 and 1. The color is divided into three tiers based on the remaining ratio: blue for approximately 20% or more, amber for 10%–20%, and red for less than 10%. The color variables use official tokens such as --dsw-static-deepseek-500, --dsw-static-amber-500, and --dsw-static-red-500.
Position and Collapsed State. When the sidebar is expanded, the widget appears at the bottom above the settings button; when collapsed, it becomes a 36px circular badge showing the condensed amount, with the full number displayed in the tooltip. The condensed display uses floor rounding to avoid overstating the balance.
Polling and Failure Fallback. The browser requests the data every 60 seconds; it will immediately refresh when the tab is reactivated. If the upstream request fails and there is a local snapshot from the last query, the interface will continue to display the old data in a faded (stale) state instead of showing an error message.

The implementation follows the pattern of “one-line plugin, two-part code”: cordis.patch.yml inserts a single line with id: balance-monitor; the server-side lib/index.js registers a /balance RPC on ctx.connection with authority: 'loopback'; the browser-side lib/client.js is a handwritten classic script with no build steps or separate CSS files. The API key only stays on the server, and the browser only sees the balance numbers. The README also notes: no telemetry, all outbound requests only go to the official balance interface.

Installation and Activation¶

The installation command provided on the catalog page can be run in the DeepSeek Harness terminal:

dsh plugin add github:jelly-000/dsh-balance-monitor

This is a UI enhancement plugin, and the widget will only appear in the Web UI. The repository README recommends explicitly installing it to the web profile and restarting the Web UI after installation:

dsh plugin --profile web add github:jelly-000/dsh-balance-monitor#main
dsh --profile web

The catalog page also reminds users that for reproducible installations, replace #main with a specific commit hash, for example:

dsh plugin add github:jelly-000/dsh-balance-monitor#<commit>

The README also includes the command dsh plugin --profile web add dsh-balance-monitor, noting that this will install from npm after an official release. As of the writing of this article, the installation should still use the GitHub source, and do not use the bare package name to avoid installing other projects with the same name.

You need to have configured your DeepSeek API Key before activation. The plugin looks for the key in the following order:
1. Environment variable DEEPSEEK_API_KEY
2. A line in $DSH_HOME/.credentials.yaml in the format DEEPSEEK_API_KEY: sk-...

If the key cannot be found, the server will return unauthorized, and the balance will be unavailable in the interface. The key parsing uses regular expression matching on the YAML file, not a full YAML parser; if your credentials file has a special format, please confirm that this line can be matched first.

What It Looks Like in Use¶

After installation and restarting the Web UI, you can find it at the bottom of the sidebar. The expanded state roughly has three lines:
- Left side: “Balance”, right side shows the current amount, e.g. ¥99.50
- A thin progress bar in the middle
- Bottom line: “Today’s Spending” plus the amount

When the sidebar is collapsed, only the circular amount badge remains; move your mouse over it to see the full number. There is no separate “refresh” button in the source code—refreshing relies on the 60-second polling interval and tab reactivation.

The state file is a local JSON located at $DSH_HOME/storages/balance-monitor.json. The example provided in the repository README is:

{
  "date": "2026-08-14",
  "dayStart": 100.0,
  "lastTotal": 99.5,
  "lastCurrency": "CNY",
  "updatedAt": 1755200000000
}

The current lib/index.js also writes a spent field when saving, to remember the accumulated spending for the day across process restarts. This file only serves local display and is not a bill export.

Applicable Scenarios and Notes¶

This plugin is suitable for users who are already using dsh web and have their DeepSeek official API Key configured in the dsh credentials file. If you only need to check the balance occasionally, opening the platform console is sufficient; the value of this plugin is to keep the balance always visible in the sidebar without switching tabs while running tasks.

There are several boundary cases to note before use:
1. Permissions and License. The catalog page clearly states that the plugin runs with the permissions of the current dsh process, and executing code may occur during installation. Please check the source code repository and license before installing. This plugin is licensed under MIT, and the source code is concentrated in lib/index.js and lib/client.js, which you can read through first before installing.
2. Today’s Spending is Not the Official Bill. The number is calculated from the difference in the balance interface, not the token details or the platform’s billing page. It cannot distinguish between granted balance and topped-up balance (although the server reads granted_balance / topped_up_balance, only the total amount and spending are returned to the interface snapshot), and it cannot统计 spending from other vendors. If you switch machines or delete the state file, the daily baseline will be recalculated based on the next successful query.
3. Only Supported for Web UI. package.json declares platform: "web". This widget will not appear in the terminal TUI or other profiles.
4. dsh is Still Under Rapid Iteration. The official README notes that compatibility-breaking changes may occur. If the slot name, credential file format, or RPC channel changes, the plugin may need to be updated accordingly.
5. Security Model. The API key never leaves the server; the RPC uses the loopback trust policy. Even so, the plugin runs in the dsh process and can read local credentials and access the network. Do not install from unknown forks.

Summary¶

dsh-balance-monitor connects the DeepSeek official balance interface to the bottom of the dsh sidebar: check remaining credit, view daily consumption, and use a thin progress bar to prompt how much balance remains. It does not modify core code, requires no build steps, and keeps the API key on the server, with the goal of eliminating the need to switch tabs once.

Catalog page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-balance-monitor/

GitHub: https://github.com/jelly-000/dsh-balance-monitor

View Balance and Today's Expense in DeepSeek Harness Sidebar via dsh-balance-monitor