Foreword

DeepSeek Harness（DSH）extends functionality through its plugin ecosystem. For developers or users, monitoring Token consumption and cost in real time across multiple sessions is a basic requirement. Existing log records often fail to present the cost structure of an individual session in an intuitive way. dsh-token-usage aims to solve this problem. It is embedded directly in the sidebar and provides a visual usage card.

Plugin Overview

This plugin is maintained by vector-sunlight and uses the MIT License. It is a DSH Web plugin that registers a “⚡ Token Usage” tab in the dsh-better-sidebar right sidebar, independently tracking the current session’s Token usage and cost.

Core Features

  1. Per-session independent tracking: Switching sessions automatically reuses or creates a dedicated window, so statistics do not interfere with one another.
  2. Detailed Token statistics: Supports separate statistics for cache hits, cache misses, cache writes, output, and reasoning tokens.
  3. Cache hit-rate visualization: Provides a cache hit-rate progress bar, with a color gradient from deep red to turquoise, intuitively reflecting cache optimization effects.
  4. Peak/off-peak time-based pricing: Determines peak and off-peak periods based on Beijing Time（UTC+8）. Peak periods are 9:00-12:00 and 14:00-18:00; all other times are off-peak. Each usage record is priced according to the period at the time it occurs.
  5. Official pricing synchronization: When the Host starts, it automatically fetches the DeepSeek official pricing page, parses dual-currency（USD/CNY）and peak/off-peak price sets, and refreshes automatically every 6 hours. If synchronization fails, it falls back to built-in prices and displays a warning.
  6. High-precision billing: Costs are accurate to two decimal places. The primary currency is displayed according to interface language（Chinese ¥ / English $）.

Installation and Enablement

Before installing, ensure that the dsh-better-sidebar plugin is installed（version >= 0.12.0）. The one-click installation script will automatically detect and handle dependencies.

Official Installation Command

Run the following command in the terminal to add the plugin:

dsh plugin --profile web add github:vector-sunlight/dsh-token-usage

Dependency Handling

The plugin declares the dsh-better-sidebar dependency through peerDependencies. The installation script automatically detects this dependency; if it is not installed, it will explicitly prompt and ask whether to install it automatically.

Operations after Startup

After installation, restart the DSH process（for example, pm2 restart dsh-web or directly restart dsh web）and perform a hard refresh in the browser（Ctrl+F5 or Cmd+Shift+R）to ensure the plugin and dependencies load correctly.

Functionality Description

Metering Reset Rules

To maintain data accuracy, the plugin includes a reset mechanism:
* Reset after context compaction: When a session triggers context compaction（compaction/end）, metering data is reset.
* One-week clearing: If one week has elapsed since the last record and there are no new records, the old metering data is automatically cleared and reset begins anew.

Price Synchronization Mechanism

When running on the Host side, the plugin fetches the DeepSeek official pricing page. It parses the model prices for different periods（peak/off-peak）and calculates costs accordingly. The top of the card displays the current Beijing Time（including month and day）in real time.

Technical Implementation

The plugin uses a separated Host and Client architecture:
* Host side（lib/index.js）: Runs as an ESM module, registers the /token-usage/api/usage JSON route, and handles session persistence logging, official-site price parsing, and segment-based pricing logic.
* Client side（lib/client.js）: Registers a tab with betterSidebar and polls the Host route every 3 seconds to fetch the latest data and update the UI.

Notes

  1. Dependency requirement: dsh-better-sidebar（>= 0.12.0）must be installed and enabled; otherwise the plugin cannot be displayed.
  2. Permissions: The plugin runs with the permissions of the current DSH process. It is recommended to review the source code and license before installation.
  3. Data source: Price synchronization depends on network access to the official website. If the network environment is restricted, it may fall back to built-in prices.

Summary

dsh-token-usage provides a complete cost-monitoring solution from cache hit-rate to peak/off-peak billing, making it suitable for developers who need to manage Token usage intuitively in the DSH sidebar. More details can be found in the catalog page or source repository.