Plugin Overview

DeepSeek Harness (DSH) provides session management capabilities, but typically lacks detailed statistics on historical Token consumption. The zcode-usage-stats plugin scans the full conversation history, aggregates daily, hourly, and per-model Token usage, and presents it using trend charts, dashboards, and heatmaps.

The plugin is maintained by qianxiao1213 and is a client-side plugin. It addresses the need for developers to review historical resource consumption, supporting switching across multiple time granularities and data visualization.

Installation and Enablement

Before installation, make sure the host environment meets the following dependencies:
* @deepseek-ai/dsh version is pinned to >=0.1.0-rc.5
* Depends on the sessionPersistence and webServer services provided by the DSH host
* Depends on the client runtime packages @deepseek-ai/dsh-client-runtime and @deepseek-ai/dsh-client-ui-slots

Run the following command to install:

dsh plugin --profile web add zcode-usage-stats

After installation, restart the DSH process. The statistics page can be found at Settings → Usage Statistics.

Core Features

The plugin includes the following capabilities:

  1. Multiple time ranges: Supports today, yesterday, last 7 days, last 30 days, this month, last month, and custom ranges. Custom ranges support year/month/day selection, and the start and end dates are automatically validated to prevent reversal.
  2. Smart granularity switching: When today, yesterday, or a single-day custom range is selected, the trend chart’s x-axis automatically switches from “day” to “hour”.
  3. Data visualization:
    • Multi-model area trend chart: Uses Catmull-Rom smoothed curves, with reference-line snapping and data-point tooltips. The legend supports clicking to show or hide individual series.
    • Model usage dashboard: Displays proportions with a ring chart, using the same measurement scope as the trend chart.
    • Activity heatmap: GitHub-style, supports collapsing columns by window day, and shows tooltips on hover with magnification.
  4. Theming and performance:
    • Colors are synced with the DSH theme (<body data-ds-dark-theme>).
    • Uses a disk + memory two-tier cache and supports stale-while-revalidate (SWR) refreshes to ensure the first screen loads instantly.

Usage Guide

  1. Switch time range: At the top of the page, click a preset time button (such as “Last 7 Days”), or click “Custom” to open a date-picker card.
  2. View trends: Hover over the trend chart to view detailed data linked to the reference line; click a legend item to show or hide a specific model’s data.
  3. Refresh data: If you need to force a rescan of all sessions, click the “Refresh” button.

Technical Details and Data Scope

  • Data sources:
    • Token usage: Based on the full usage payloads carried in assistant/message events, with deduplication applied.
    • Turn counts: Counted as new turns based on step/end events.
    • Model classification: Unknown models are grouped under other.
  • Caching strategy: Uses a stale-while-revalidate strategy; after expiration, the cache is updated automatically to avoid blocking first-screen rendering.

Use Cases

Suitable for developers or teams that need to manage DeepSeek session costs precisely and analyze usage frequency across different models. With heatmaps and trend charts, they can quickly identify active time periods and model preferences.