Introduction

When running agents with DSH (DeepSeek Harness), tokens are the most direct cost signal: how many were used during a certain period, how many cache reads/writes occurred, and which provider and model consumed the most all require a ledger that can be persisted and queried at any time. DSH includes a built-in usage accumulator and corresponding usage page, which is sufficient for basic viewing; however, if you want to separate the four types of usage reported by the service provider into distinct accounts, perform daily statistics based on local dates, or read this data in your own plugin, you need a standalone statistics component. The Mu-scorpio/token-usage-counter introduced below is exactly such a plugin.

What is this

Its positioning in one sentence: provides persistent, service-provider-reported token usage statistics for DeepSeek Harness, supporting cumulative, daily, per-session, and per-model views.

  • Maintainer: Mu-scorpio
  • npm package name: dsh-token-usage-counter, current version 0.4.0
  • License: MIT (README and package.json are both MIT)
  • Compatible Environment: Node.js 22.13.0 or newer; DSH 0.1.2-alpha.3 to 0.1.2-alpha.5; Profile: web

Core Features

The capabilities provided by the plugin are as follows:

  • Bucket statistics: saves the four types of usage reported by the service provider—uncached input, cache reads, cache writes, and output—separately;
  • Persisted totals: data is stored in the plugin-specific dsh-token-usage-counter settings namespace;
  • Multiple views: provides three types of summaries: global, session, and provider/model;
  • Daily activity: statistics token totals and call counts based on local dates;
  • Built-in settings page: comes with a Web settings view and a heatmap;
  • Safe counting: counts usage only after successfully completing an anchor (completion anchor);
  • Interactive command: registers /tokens when the command service is mounted;
  • API: provides ctx.tokenUsageCounter (getSummary / getSession / getModel / formatSummary).

Counting Rules

The reliability of statistics depends on the counting rules. The plugin listens to the persisted session event stream, with the following rules:

  1. assistant/message.usage is counted only once;
  2. compaction/summary.usage is counted as one provider call;
  3. assistant/chunks with only usage are temporarily stored first, and are booked only when the matching assistant/message arrives;
  4. When a chunk describes the same round and step as the final message, the earlier sample is replaced by the final value;
  5. Failed requests, retries, and fork seed history are not counted repeatedly.

The first two determine the granularity of booking, and the last three avoid repeated counting caused by streaming sampling and retries; combined with the strategy of “counting usage only after successfully completing an anchor,” the statistical approach is quite conservative.

Installation and Activation

First, confirm that the runtime environment meets the compatibility requirements above, then install the published Bundle into the web profile:

dsh plugin --profile web add -w --config.auto-install-peers=false dsh-token-usage-counter
dsh web

The first command installs dsh-token-usage-counter into the web profile, and the second command starts dsh web. After the steps above, the plugin can run together with dsh web.

It is worth noting that this Bundle is incremental: it only mounts the plugin’s own token-usage-counter entry, while the built-in DSH usage accumulator and usage page remain enabled; they coexist.

Upgrade Notes

0.4.0 migrates persistence from the shared usage-stats namespace to the plugin-specific dsh-token-usage-counter namespace. Since the shared namespace belongs to a built-in plugin, the existing totals in 0.3.x will not be silently migrated; the new counter starts from a separate snapshot after upgrading. If you are still using 0.3.x and care about the old cumulative data, please confirm this before upgrading.

Local Development

If you want to modify this plugin locally, complete the build inside the repository checkout first:

npm install --ignore-scripts --legacy-peer-deps --no-package-lock
npm run build
npm run verify

The generated host and client bundles are committed to the lib directory.

During debugging, use the following command to overlay the source code into dsh web without replacing built-in components:

dsh web --patch ./cordis.yml

You can also manually compose it by only adding the plugin’s own entries:

- insert:
    - id: token-usage-counter
      name: './src/index.ts'

Typical Usage

Interactive Command

When the command service is mounted, the plugin registers the /tokens command, which can be called within a session to view statistics.

API

Other plugins can read data via ctx.tokenUsageCounter:

ctx.tokenUsageCounter.getSummary()
ctx.tokenUsageCounter.getSession(sessionId)
ctx.tokenUsageCounter.getModel(provider, model)
ctx.tokenUsageCounter.formatSummary()

The four methods correspond to global summary, session usage by sessionId, model usage by provider and model, and formatted summary text.

Applicable Scenarios and Notes

Suitable scenarios:

  • Need to calculate costs based on four metrics (uncached input, cache reads, cache writes, output);
  • Need to review token totals and call counts based on local dates, or observe activity distribution via the heatmap in the settings page;
  • Want to perform further processing of usage data in your own plugin via ctx.tokenUsageCounter.

Pre-use notes:

  • The plugin runs with the permissions of the current dsh process; you should check the source code and license before installing. The source code of this project is public on GitHub with an MIT license;
  • Verification results for each version and one-time profile evidence are recorded in docs/VERIFICATION.md; you can check them before choosing a version;
  • After upgrading from 0.3.x to 0.4.0, the old totals will not be migrated automatically; see the section above for handling.

Summary

token-usage-counter focuses on a specific task: separating the four types of token usage reported by the service provider, persisting them, and providing queries from four perspectives: global, daily, session, and model. It can also be reused by other plugins via API. If your DSH workflow requires a reliable usage ledger, you can install and try it directly using the command above.

  • GitHub: https://github.com/Mu-scorpio/token-usage-counter
  • npm: https://www.npmjs.com/package/dsh-token-usage-counter
  • Community Directory Page: https://www.skillhub.cn/plugins/Mu-scorpio/token-usage-counter (The directory is independently maintained by the community and has no official affiliation with DeepSeek / Huanfuan)