Developers using DeepSeek Harness (DSH) for API-based development or debugging need real-time visibility into their account balance and local token consumption. Since DeepSeek has not published a detailed usage-query API, manually aggregating local session logs is both tedious and error-prone. This article introduces a community-maintained plugin that solves both balance lookup and usage aggregation through a command-line interface.

Plugin Overview

The plugin is named dsh-deepseek-usage, maintained by developer kane-le and released under the MIT License. It is a DSH plugin designed to provide real-time account balance lookup via the /usage command and aggregate token usage from local DSH session logs.

Core Features

The plugin mainly provides the following capabilities:

  1. Query the official account balance in real time: Call the GET https://api.deepseek.com/user/balance endpoint to obtain account availability, total balance / top-up balance / gift balance for each currency.
  2. Aggregate local DSH session logs: Parse local session log files and count input tokens, output tokens, cached-read tokens, and reasoning tokens.
  3. Incremental scanning: Support incremental scanning of session logs. After the first scan, subsequent queries read only new content, saving time.
  4. Automatically handle compressed logs: Support automatic parsing of zstd-compressed log files (session.jsonl.zstd) without external decompression tools.

Installation and Enablement

The plugin is installed via the plugin manager. Make sure DeepSeek Harness is already installed.

  1. Download the plugin source code locally, for example save it as /path/to/dsh-deepseek-usage.
  2. Run the following command in the terminal to add the plugin:
dsh plugin --profile web add /path/to/dsh-deepseek-usage
  1. After installation, restart the dsh web process. The plugin is automatically included in the profile bundles.

Typical Usage

After installation and restart, you can invoke the following commands from the Web UI or command line:

Command Description
/usage View the full report: cumulative local token usage + real-time balance
/usage balance Query balance only, without scanning logs
/usage rescan Force a full rescan of all session logs and output the full report

Example output:

DeepSeek API Usage and Balance
================================
[Usage] Local cumulative (session logs + real-time tracking)
  Input tokens:      196,267
  Output tokens:      107,874
  Cached-read tokens:  6,773,172
  Reasoning tokens:    54,537
  Sessions: 9 | Last activity: 2026-08-24 18:11:51 UTC
  ...
[Balance] Real-time query
  Account available: Yes
  CNY total balance 2.04 | Top-up 2.04 | Gift 0.00

Technical Details

API Key Resolution Order

The plugin attempts to obtain the API Key in the following order:

  1. Official credentials service (configuration written via the Web UI: Settings → Models).
  2. Environment variable DEEPSEEK_API_KEY.
  3. The DEEPSEEK_API_KEY line in the local configuration file $DSH_HOME/.credentials.yaml.

Endpoints and Log Paths

  • Endpoint: Default is https://api.deepseek.com; can be overridden by the environment variable DEEPSEEK_BASE_URL.
  • Log path: $DSH_HOME/sessions/*/*/session.jsonl[.zstd].
  • Data storage: The usage ledger is stored in $DSH_HOME/storages/deepseek-usage.json.

Data and Idempotency

  • Deduplication mechanism: Usage data is deduplicated and merged using the session:round:step key. Real-time events and log rescan share the same key space, preventing duplicate counting.
  • Incremental scanning: Log scanning is based on file size and modification time (mtime). After the first full scan, subsequent commands read only new content.
  • Decoding method: Log files use the zstd multi-frame format. The plugin uses node:zlib for decoding and does not depend on external tools.

Use Cases and Notes

  • Target users: Users who use DeepSeek Harness for development or debugging and need to monitor API consumption.
  • Data source note: Usage data is entirely derived from local session logs. Since DeepSeek’s official API does not expose a usage-query endpoint, the plugin implements aggregation by parsing logs.
  • Permission note: The plugin runs with the permissions of the current dsh process. Review the source code and license before installation.