When developing agents with DeepSeek Harness (DSH), monitoring Token consumption and cache efficiency is a critical step for controlling costs and optimizing performance. Manually parsing session.jsonl.zstd files to obtain statistics is time-consuming and error-prone.

The dsh-token-usage-xc plugin, maintained by xchannel1987, is introduced below. It aims to provide real-time, visualized Token usage statistics and trend analysis. It supports model-based bucketing, cache hit rate calculation, persistent storage, and RPC interfaces.

Core Features

Real-Time Usage Statistics

The plugin adds a “Today’s Token Usage” section to the settings page, displaying detailed model-based data in real time, including:
* Input Tokens (uncachedInput)
* Output Tokens (output)
* Cache Read Tokens (cacheRead)
* Cache Write Tokens (cacheWrite)
* Request Count

Cache Hit Rate Analysis

The plugin automatically calculates the cache hit rate using the formula:

cacheRead / (uncachedInput + cacheRead) × 100%

This helps evaluate the effectiveness of cache strategies.

7-Day Trend Chart

A stacked bar chart displays the Token consumption trend over the last 7 days. It supports switching dates to view historical data and filtering by model to view consumption for a specific model.

Session Top Bar Badge (Optional)

After enabling “Show today’s total Tokens in the session top bar” in settings, the session page top bar displays a badge for today’s total Tokens.
* Click the badge to quickly view the details.
* Supports simplified displays such as K/M/B, with hover to view exact values.
* The layout is optimized for mobile devices (≤1023px); the badge is placed second from the right and does not overlap the background task icon.

Data Persistence

Data is persisted to local files by day to ensure it is not lost after restart.
* Storage path: ~/.dsh/storages/dsh-token-usage-xc/<YYYY-MM-DD>.json
* Policy: If startup occurs before the plugin loads, today’s usage is automatically backfilled; older data is automatically cleaned up after 7 days.

RPC Interface

The plugin provides RPC interfaces for other plugins to call, making it easier to integrate into more complex workflows.

Installation and Enabling

Add the plugin using the official installation command:

dsh plugin --profile web add dsh-token-usage-xc

After installation, restart DSH to see the new “Today’s Token Usage” section in the settings page.

Usage

  1. View Today’s Usage
    Open DSH settings, find the “Today’s Token Usage” section, and view the detailed model-based data.

  2. View the 7-Day Trend
    In the usage panel, click the “Trend” tab to view the stacked bar chart. Click a date to view details, with support for model filtering.

  3. Enable the Top Bar Badge
    Enable “Show today’s total Tokens in the session top bar” in settings to turn on the badge. Click the badge to quickly view the details.

Data Source and Metric Definitions

  • Data Source: Listens to the usage field in session/event events, deduplicates by seq, and ensures exactly one entry per assistant/message.
  • Total Token Calculation: uncachedInput + cacheRead + cacheWrite + output.
  • Archiving Rule: Archives records by event.time into YYYY-MM-DD.
  • Compatibility: Compatible with DSH 0.1.7-rc.1 or later.

Notes

  • The plugin only counts final usage data sourced from session/event events.
  • The plugin runs with the permissions of the current DSH process. It is recommended to review the source code and license (MIT) before installation.

Summary

dsh-token-usage-xc addresses the pain points of Token statistics in DSH through local persistence and visual charts. Whether for daily cost monitoring or analyzing cache optimization effects, the plugin provides structured data support.

For more information and the source code, visit:
* GitHub
* DSH Plugin Catalog