Introduction

DeepSeek Harness (DSH) organizes its extensibility capabilities around a plugin mechanism. For developers using DSH for session and agent development, Token consumption, model usage distribution, and DeepSeek account balance are data points that typically require daily attention.

dsh-token-stats is a DSH plugin maintained by huantian1223 with an MIT license. It parses real provider usage from DSH session logs session.jsonl.zstd, does not estimate or capture packets, and organizes the usage into statistical information, heatmaps, model/workspace rankings, session badges, and balance information.

Below introduces what this plugin can do, how to enable it, and a few common entry points for daily viewing.

What is it

The positioning of dsh-token-stats is a Token usage statistics plugin for DeepSeek Harness. It targets local DSH session logs and solves the problem of “seeing the calls but not conveniently seeing the usage structure.”

It primarily provides several categories of information:

  • Cumulative, today’s, peak Token, longest chat duration, current consecutive days, and longest consecutive days.
  • GitHub-style 12-month activity heatmap, supporting daily, weekly, and cumulative views, as well as 12-month, 3-month, and 30-day range switching.
  • Consumption composition of input, output, cache read, cache write, and reasoning.
  • Consumption rankings by model and workspace dimensions.
  • Current session Token badge in the session header and DeepSeek account balance badge.
  • DeepSeek account balance display and refresh, as well as balance warnings.
  • Independent statistics page, drill-down session details by date, merge sessions with duplicate titles, pagination, and CSV export.

Data Source

The plugin does not rely on external estimation nor packet capture. It reads the real provider usage recorded in DSH session logs session.jsonl.zstd and generates statistical results based on this data.

Statistical results are stored in:

$DSH_HOME/token-stats/usage.jsonl

Where $DSH_HOME is the DSH data root directory, defaulting to ~/.dsh, and can also be specified via the DSH_HOME environment variable.

Core Features

Usage Statistics

The page displays cumulative Token, today’s Token, peak Token, as well as longest chat duration, current consecutive days, and longest consecutive days.

Activity Heatmap

The heatmap adopts a GitHub-style design covering a 12-month window. You can switch between daily, weekly, and cumulative views, as well as 12-month, 3-month, and 30-day ranges.

Consumption Breakdown & Rankings

The plugin breaks down consumption into input, output, cache read, cache write, and reasoning, and displays consumption rankings in both model and workspace dimensions.

Session Badges & Balance

The session header displays the current session Token badge and the DeepSeek account balance badge. The balance can be displayed and refreshed; when the balance is lower than the configured threshold, a red balance warning is triggered.

Regarding balance-related requests, the API Key is parsed via the DSH credential service and is used only within the host process, never sent to the browser.

Independent Statistics Page

The plugin provides an independent statistics page:

http://127.0.0.1:3080/token-stats

This page can be accessed directly to view statistics, balance, details, and export CSVs.

Installation and Enablement

The plugin is enabled via DSH’s web profile mechanism. First, ensure the local Node environment meets the version requirements declared in the package:

"engines": {
  "node": ">=22.13"
}

Then, enable it by following these steps:

  1. Add the dsh-token-stats dependency to the package.json of the web profile and add it to the dsh.profile.bundles list. For example:
{
  "dependencies": {
    "dsh-token-stats": "link:../dsh-token-stats"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-token-stats"]
    }
  }
}
  1. Execute dependency installation in the profile directory:
pnpm install
  1. Restart DSH.

After the above steps, the plugin will load together with DSH’s web profile.

Typical Usage

Access the independent statistics page:

http://127.0.0.1:3080/token-stats

In the daily view of the heatmap, clicking on a date cell allows you to view the session details for that day. Sessions with duplicate titles are merged and displayed, and pagination is supported.

When exporting CSV, the plugin exports daily data for the current range. The file includes a UTF-8 BOM, making it suitable for direct use with spreadsheet software.

To view the currently effective configuration, you can request:

GET /token-stats/api/config

The balance warning threshold is controlled by balanceWarnThreshold. The default is ¥5; setting it to 0 turns off the warning.

Configuration

Plugin configuration is located in:

$DSH_HOME/token-stats/config.json

After modifying or adding configuration, you need to restart DSH for it to take effect.

Verified adjustable parameter examples are as follows:

{
  "balanceWarnThreshold": 5
}

Here, balanceWarnThreshold controls the DeepSeek account balance warning threshold, with a default value of ¥5. Setting it to 0 means turning off the warning.

Use Cases and Notes

Suitable for the following scenarios:

  • Using DSH web profile and needing to view local Token usage.
  • Needing to distinguish between input, output, cache read, cache write, and reasoning consumption.
  • Needing to view consumption rankings by model or workspace.
  • Needing to pay attention to the DeepSeek account balance and configure low balance warnings.
  • Needing to export daily data as CSV for subsequent analysis.

Notes:

  • The plugin runs with the permissions of the current DSH process; the source code and MIT license should be checked before installation.
  • It relies on real provider usage in DSH session logs, not a general packet capture statistics tool.
  • DSH needs to be restarted after modifying configuration.
  • The enablement method provided in this article is based on the profile package.json and pnpm install; a single unverified dsh plugin add command is not provided.
  • The community directory is an independent site and has no official affiliation with DeepSeek / Huanfang.
  • Directory page: https://www.skillhub.cn/plugins/huantian1223/dsh-token-stats
  • GitHub: https://github.com/huantian1223/dsh-token-stats