Preface

When running agents with DeepSeek Harness (DSH), the model providers are often more than one: the official DeepSeek, OpenRouter relay, Kimi Coding Plan, Z.ai subscription window… Conversations happen within the Harness, but balances and quotas are scattered across various control panels. How many tokens have been used, what is the cache hit rate, and which model is the most token-consuming today—the Harness’s native interface also lacks an “overview dashboard.”

The community plugin dsh-usage-stats (maintainer Ychris12138, npm package name @ychris12138/dsh-usage-stats) targets the dsh web interface, bringing multi-provider account monitoring and local token aggregation analysis into the sidebar’s “Usage/Balance” panel. This plugin is categorized as “Client-side” in the SkillHub Plugin Repository, has approximately 119 stars and 15 forks on GitHub, and is licensed under the MIT license.

It’s important to note that DSH’s core philosophy is “everything is a plugin.” Community directories like SkillHub and deepseek-harness-plugin.com are maintained by enthusiasts and have no official affiliation with DeepSeek / High-Flyer. Please review the source code and license yourself before installation. The plugin runs with the permissions of the current dsh process. When querying accounts, it reads the credential references already configured on your local machine and does not send API keys to the browser.

What Is This

One-sentence positioning: A visual client-side plugin for DeepSeek Harness Web GUI that provides provider balances, subscription quotas, and token usage analysis.

The data sources are split into two parts:

  1. Local Token Statistics: Aggregates the usage field reported by the provider within the assistant/chunk or assistant/message entries from the Harness’s persistent session logs, grouped by date, provider, and model.
  2. Remote Account Snapshots: For providers with public balance/quota endpoints configured, the server periodically fetches the remaining balance or Token Plan window amount.

The interface supports Chinese and English; the browser only requests the currently selected provider, and the backend refreshes configured accounts every five minutes, regardless of whether the panel is open.

Core Features & Highlights

Unified Account Cards

The panel displays only the currently selected provider’s card at a time:

  • Balance-based (e.g., DeepSeek, Moonshot, OpenRouter): Shows the available balance and warning status.
  • Subscription/Token Plan-based (e.g., Kimi For Coding, MiniMax, Ollama Cloud, Z.ai): Shows quotas and remaining ratios across different time windows.

Providers without public account endpoints will still have their tokens tracked; the card will indicate “Balance query not supported” and will not guess the value.

Token Usage Analysis

  • Usage for today, this month, and cumulative totals, along with cache hit rate.
  • Monthly heatmap, supporting navigation with ‹ / › to switch months. Clicking a date drills down into the provider/model details for that day.
  • “Last 14 days” is calculated based on the local calendar and only displays dates with records within the window.

Extensible Adapters

In addition to built-in adapters for DeepSeek, OpenRouter, Moonshot, etc., it also supports:

  • Relay protocols like New API, Sub2API / Passion.
  • sub2api-auth: Uses the provider’s own inference key to read the Sub2API panel balance and can automatically identify real Sub2API deployments.
  • declarative: Declarative custom queries using limited GET + JSON Pointer, without executing JavaScript.

warning.warnBelow / warning.criticalBelow can set absolute balance thresholds; scenarios with a total quota will automatically generate normal / warning / critical status based on the remaining ratio.

Local Security Boundary

The five design principles emphasized in the official README are worth understanding before installation:

  • The five API endpoints only accept GET requests from the loopback address; non-GET requests return 405, and requests from non-loopback addresses return 403.
  • API keys, cookies, and management PATs are only parsed server-side and do not enter browser responses, plugin caches, or logs.
  • The usage cache ~/.dsh/storages/usage-stats-cache.json only stores aggregated tokens and session revisions, not prompts or reply content.
  • Custom monitors default to requiring HTTPS, same-origin relative paths, and limit the response body size.
  • Do not expose the plugin endpoints to the LAN or public internet via a reverse proxy.

Installation & Activation

Prerequisite: Requires the web profile of DSH and @deepseek-ai/dsh >= 0.1.0-rc.6.

The command is as follows (note the web profile and GitHub source):

dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"

After installation, restart the running dsh web and hard-refresh the browser. A “Usage/Balance” entry will appear at the bottom of the sidebar.

To ensure reproducible installation, you can pin a specific commit:

dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats#commit"

To upgrade or uninstall:

dsh plugin --profile web update "@ychris12138/dsh-usage-stats"
dsh plugin --profile web remove "@ychris12138/dsh-usage-stats"

The deepseek-harness-plugin.com directory also lists this plugin, with the shorthand installation being dsh plugin add github:Ychris12138/dsh-usage-stats. If you typically use the web profile, the command above with --profile web matches the README and is less likely to install the wrong profile.

Alternative: Compatible Installer via npx

If you cannot use dsh plugin, you can use the following command (works in PowerShell, cmd, macOS/Linux terminals):

npx --yes github:Ychris12138/dsh-usage-stats

The installer will copy files to ~/.dsh/profiles/node_modules/@ychris12138/dsh-usage-stats and idempotently write to profiles/web/cordis.patch.yml. dsh plugin and npx are two independent paths; do not keep both a manual Cordis entry and bundle registration simultaneously, or it will result in duplicate mounting.

To preview and check:

npx --yes github:Ychris12138/dsh-usage-stats --dry-run
npx --yes github:Ychris12138/dsh-usage-stats --check

Plugin Market GUI Installation (Optional)

This repository has been integrated as a DSH Community Market standard source (Path A). Since the name dsh-usage-stats on npm is already taken, the catalog uses the scoped name @ychris12138/dsh-usage-stats (current catalog version 0.2.10). To use the “Install” button in the market GUI, the maintainer first needs to publish the scoped public npm package and publish the catalog to GitHub Pages. Until then, the GitHub / dsh plugin path is more straightforward.

Credentials & Typical Configuration

Credentials are parsed by Harness from ~/.dsh/.credentials.yaml; the installer does not read or modify this file. Do not commit real keys to Git or paste them to coding agents.

Balance-based Provider Example

Providers like DeepSeek and Moonshot typically reuse the apiKeyEnv from their corresponding provider profile:

# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: sk-your-key-here

OpenRouter is a notable exception: its account credits endpoint requires a Management Key, which cannot reuse the standard inference OPENROUTER_API_KEY:

OPENROUTER_MANAGEMENT_KEY: sk-or-v1-your-management-key

Token Plan Provider Example

OPENCODE_GO_API_KEY: sk-opencode-your-key
ZAI_API_KEY: your-zai-key
KIMI_API_KEY: your-kimi-key
MINIMAX_API_KEY: your-minimax-key
OLLAMA_API_KEY: sk-ollama-your-key

For Chinese region Z.ai / MiniMax, you can set ZAI_API_REGION=bigmodel-cn and MINIMAX_API_REGION=cn respectively.

Custom Monitor (Excerpt)

Merge config under the existing @ychris12138/dsh-usage-stats Cordis entry; do not append a second plugin entry. The monitor keys must correspond to real provider IDs in Harness:

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: "@ychris12138/dsh-usage-stats"
      config:
        monitors:
          relay-a:
            adapter: new-api
          relay-b:
            adapter: sub2api-auth

If a Sub2API panel is already configured as a regular provider in DSH, the plugin can detect GET /api/v1/settings/public and automatically read the balance using sub2api-auth, usually without needing to write a separate adapter.

Typical Usage

  1. Start dsh web and open the conversation interface.
  2. Click “Usage/Balance” in the sidebar.
  3. Use the “Current Provider” dropdown to switch account cards.
  4. In the heatmap area, use ‹ / › to switch months and click a day to view provider/model details.
  5. Refreshing the title bar updates the token aggregation, provider list, and forces a refresh of the current account snapshot.

The statistics are based on the usage reported by the provider, not local estimates; subsequent samples in the same turn replace older samples. Manual refresh does not force a batch request to other providers’ remote accounts.

Applicable Scenarios & Notes

Who is this for:

  • Developers who work long-term in dsh web and use multiple APIs or Coding Plans.
  • Agent users who need an at-a-glance view of “how many tokens spent today, which provider’s balance is running low” on their local machine.
  • Those operating New API / Sub2API relays who want to check relay balances directly within Harness.

Notes:

  • Only applicable to the web client; TUI or other profiles are out of scope.
  • Read SECURITY.md before installation to confirm the network boundary and credential handling meet your security requirements.
  • Upstream Bearer usage interfaces like OpenCode Go may change with official updates; pay attention to plugin version updates.
  • The plugin depends on Harness pre-release interfaces (Cordis, session persistence, etc.). Major version upgrades may require synchronized plugin updates.

Conclusion

If you are already connected to several models within Harness but still switching between browser tabs and various control panels, dsh-usage-stats brings balances, quotas, and token heatmaps into the sidebar. It is currently one of the more complete “usage dashboard” solutions in the community. The approximately 119 stars on GitHub also indicate that many DSH users indeed need this layer of visualization.

The installation command again:

dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"

After restarting dsh web, open “Usage/Balance” and start by looking at your most frequently used provider.