Introduction

When running sessions with DeepSeek Harness (DSH), token usage is scattered across various session logs. To know how much each model consumed this month and on which days it was most frequent, one has to manually flip through logs or write a script themselves. This is time-consuming and prone to errors. dsh-token-stats is a token usage statistics plugin built for the DSH Web UI. It takes session logs as the data source, aggregates usage into views by day and by model, and displays it directly in the settings panel. Below is an introduction to its features, installation methods, and working principles.

What is it

dsh-token-stats is maintained by MoonlitDropOfBlood and follows the MIT License. The README states that this project is a community plugin based on DeepSeek Harness and is not an official DeepSeek product.

Its positioning is clear: it does not modify the session flow, does not parse request headers, and directly uses DSH session logs as the sole authoritative data source to aggregate daily token usage for each model.

Core Features

Chart capabilities:

  • Two stat tabs: Last 7 days / Last 30 days (both include today)
  • Stacked bar chart: Daily consumption for each model within the period; hover to see specific numbers
  • Pie chart: Total consumption share for each model within the period; legend includes precise values and percentages
  • GitHub-style heatmap: Daily activity over the last year; days adapt to container width, displaying up to 365 days (one year)
  • Summary card: Total Tokens / Input (including cache) / Output within the period

Data & Experience:

  • Local persistence: Aggregation results are saved to <DSH_HOME>/data/dsh-token-stats/stats.json. Cold start only scans new sessions, opening is instant
  • Auto-refresh: Refreshes every 30s while the page is open; polls progress every 2s during historical backfill
  • Theme adaptation: All use DSH design tokens; light and dark themes adapt automatically
  • Deduplication: Deduplication based on session+seq watermark; no double counting after merging historical backfill with real-time monitoring

Installation & Enablement

This is a standard DSH bundle: package.json declares dsh.bundle.patch, and the package includes cordis.patch.yml. Install it using the official dsh plugin command:

dsh plugin --profile web add https://github.com/MoonlitDropOfBlood/dsh-token-stats/releases/download/v1.2.0/dsh-token-stats-1.2.0.tgz

dsh plugin add installs the plugin as an npm dependency for the profile and appends it to dsh.profile.bundles. Upon startup, DSH automatically applies the cordis.patch.yml inside the package to mount the plugin.

For local development, you can symlink to this repository, and changes take effect immediately:

dsh plugin --profile web add /path/to/dsh-token-stats

After restarting DSH, open the Web UI settings (bottom of sidebar). The Token Statistics page appears in the left navigation.

Uninstall:

dsh plugin --profile web remove dsh-token-stats

Typical Usage

  1. Open Settings → Token Statistics.

  2. Switch between the Last 7 days / Last 30 days tabs:

  • The bar chart shows daily consumption for each model within the period (stacked)
  • The pie chart shows the total consumption share for each model within the period
  • The top card gives the total Tokens / Input / Output for the period
  1. The daily activity heatmap below shows a longer time range: the more cells, the wider the container, covering up to the last year.

If you want to force a full rescan of historical data, simply delete the aggregation file. The next startup will rescan all sessions:

rm <DSH_HOME>/data/dsh-token-stats/stats.json

How it Works

Data collection follows two paths, real-time and historical, which are merged and written to disk together:

  • LIVE: After the plugin starts, it listens to assistant/message (usage) in session/events for real-time accumulation
  • HISTORY: Backfills history via sessionQuery.readSession(), scanning only sessions that have never been backfilled
  • DEDUP: Deduplicates based on the session+seq watermark, never counting twice
  • PERSIST: Writes aggregation results and watermarks to stats.json (debounce write + flush on stop)

Historical backfill only counts calls that occurred before the plugin started; real-time monitoring only counts calls after the start. They are merged via the event sequence watermark of each session and will not duplicate.

Aggregation rules:

  • Data is aggregated by local calendar day × model (provider::model)
  • total = input + output + cacheRead + cacheWrite
  • Model information comes from message.source (kind = ‘model’) of assistant/message

Code structure:

dsh-token-stats/
├── index.js            # Host half: TokenStatsService (Remote service, collection + backfill)
├── client.js           # Client half: "Token Statistics" UI bundle for settings page
├── typert.host.js      # Typert Host manifest (tokenStats/getStats description)
├── cordis.patch.yml    # dsh bundle patch (mounting line)
├── AGENTS.md           # Development guide for AI agents (including pitfalls)
└── LICENSE             # MIT

Regarding dependencies, peerDependencies declares @deepseek-ai/cordis ^4.0.1 and @deepseek-ai/dsh-typert-protocol ^0.1.0-rc.7. Runtime dependencies include zod ^4.4.3.

Scenarios & Notes

Suitable for two groups of people:

  • Developers who use DSH daily and want to understand the consumption distribution of each model and long-term activity trends
  • Developers who want to write DSH plugins; AGENTS.md records the complete mechanism and pitfalls of official DSH plugins (Host/Client/Typert trio) and can serve as a reference

Note before installation: The plugin runs with the permissions of the current dsh process. It is recommended to check the source code and license before installing. This project is a community plugin and is not an official DeepSeek product.

Summary

After installing dsh-token-stats, you can directly see the daily token consumption and long-term activity trends for each model in the Web UI, without having to manually flip through session logs. Repository address: https://github.com/MoonlitDropOfBlood/dsh-token-stats , Community directory page: https://www.skillhub.cn/plugins/MoonlitDropOfBlood/dsh-token-stats .