Introduction

The DeepSeek Harness (DSH) ecosystem emphasizes “everything is a plugin.” During local debugging or normal usage, checking token consumption and model invocations is a common requirement. dsh-plugin-token-usage is a client plugin maintained by Hjay1101. It directly reads local session logs, converts the data into a GitHub-style heatmap, and provides a model breakdown view at different granularities.

Core Features

The plugin provides the following capabilities:

  • GitHub-style heatmap: Displays token usage for the last 30 days. It uses a “Sunday-first” column layout, and today’s data is highlighted with an outline. Days with zero usage are rendered as empty.
  • Multi-granularity switching: Supports switching between “day / week / month” views. The color scale is automatically renormalized based on the current granularity range.
  • Interactive details: Hovering over a cell displays the token count, request count, and cache hit rate for that day.
  • Model breakdown table: Aggregates model data according to the current granularity. It provides precise in-window aggregation (based on second-level mappings of session × day and model × day) and supports filtering out models that only generated requests but no actual tokens.
  • Sidebar badge: Hovering over the sidebar icon displays “today’s usage.” It also performs silent background polling at a 30-second interval, and the data automatically rolls over at midnight.
  • Command-line tool: Query token usage directly in a conversation by using the usage_report model tool.
  • Theme adaptation: All colors are mapped to DSH theme variables, supporting automatic switching between dark and light modes.

Installation and Enabling

Before installation, ensure the current DSH version is at least 0.1.2-rc.1.

  1. Run the installation command:
    dsh plugin --profile web add dsh-plugin-token-usage

The plugin package includes `cordis.patch.yml`, and it is automatically mounted after installation.

Usage

  • Web interface: Click the bar chart icon in the sidebar settings row to open the token usage modal.
  • Conversation invocation: In chat, instruct the Agent to call the usage_report model tool (for example, use the refresh parameter to force a refresh, or the top parameter to limit the number of displayed rows).

Notes

  • Local operation and privacy: The plugin only performs read-only parsing of log files under ~/.dsh/sessions/** (streaming zstd decompression supported). It does not send any network requests, collect telemetry data, or perform any write operations.
  • Environment dependencies: The local environment must have React 18.2.0 and DeepSeek-related Cordis and Schemastery dependencies for runtime use.

Conclusion

This is a purely local, read-only token analysis tool, suitable for DSH users who need detailed tracking of model invocation costs.