Preface¶

In DSH (DeepSeek Harness), usage statistics are non-existent: how many tokens the plugin has run, which day was used most frequently recently, and the proportion of each model, all have to be found by manually checking session logs. DSH’s philosophy is “everything is a plugin,” and such gaps are usually filled by community plugins. Below is dsh-usage-stats maintained by ailawu0409. It adds a Usage Statistics section to Settings, providing a summary of local session tokens, an active heatmap, daily trends by model, and model proportions all at once.

A prerequisite: this is a community plugin, not officially produced by DeepSeek and not endorsed by DeepSeek; the plugin directory page is categorized as admin-security, has 0 stars on GitHub, and the repository was created on 2026-11-05. Before installation, it is recommended to read the source code and license (MIT).

What is this¶

dsh-usage-stats is a DSH plugin, package version 0.2.1, execution environment requires Node.js 22 or higher, and has no third-party runtime dependencies. It renders the statistics results in Settings → Usage Statistics (located below Archived sessions). All data comes from local session logs, is read-only, does not connect to the internet, and uploads no content.

The target host version is DeepSeek Harness 0.2.2-rc.1. The navigation icon relies on the settings.section.icon slot introduced in 0.2.2; older hosts will simply fall back to the default gear icon without throwing an error.

Core Features¶

The functions introduced below can all be verified in the README.

1. Overview Metrics (3 items): Total tokens, daily peak tokens, longest session duration.

2. Token Active Heatmap: A weekly grid in GitHub style, supporting Daily / Weekly / Cumulative color modes; hovering over a cell shows the date, token count, and number of turns, e.g., Oct 27, 2026 / 506K tokens · 2 turns. Cells are fixed at 11px, and the number of weeks adapts to the panel width (max 53 weeks, min 13 weeks). The summary interval description will specify the actual range, e.g., “Active 2 days over the last 8 months”.

3. Daily Token Trend: Smooth curves colored by model, optional Last 7 days / Last 30 days; hovering shows a vertical cursor, highlights, and model-specific details for the day.

4. Model Usage: Donut chart paired with a percentage list (top 5 models plus Other), hovering over a sector displays the model’s tokens and percentage.

5. Other: Follows the host’s light/dark theme and official fonts, the interface is bilingual (Chinese/English), and there is a Refresh button in the bottom right corner; the page header only retains the title (using the host’s setting title font size, 16px). When refresh fails, the original data is retained, and only a retryable banner appears at the top.

Data Methodology¶

This part determines why the numbers look the way they do and is worth understanding first.

• Total tokens: Sum of usage for each assistant/message, prioritizing totalTokens, otherwise using inputTokens + outputTokens.
• Peak tokens: The maximum value of daily usage, calculated based on calendar days in the local timezone.
• Longest session: The maximum sum of turn/start → turn/end duration within a single session. Idle time spanning across midnight is not counted.
• Turns: Collected based on the start date of turn/start; turns crossing midnight are counted in the earlier day.
• Heatmap summary: Only counts the intervals actually drawn in the grid, excluding historical data outside the window.
• Deduplication: Forked sessions skip the inherited prefix (seq < inheritedEventCount) and are not counted multiple times with the parent session.
• Deleting does not reduce history: After archiving, moving out of storage, or permanently deleting a session, the already counted usage remains in the total, peak, heatmap, and model proportions. The footer will indicate “N of the counted sessions are no longer listed”. This is an intentional design to avoid the counterintuitive behavior of “deleting a record reduces the numbers”.
• Failure retention: Sessions that fail to read or are in a migration-required state will not cause the cumulative value to shrink; the previous result is used. Only sessions that have never been counted are marked as skipped. Failed sessions are retried only after a 5-minute cooldown, not on every scan.
• Session limit: Statistics are limited to a maximum of 20,000 sessions, with a prompt displayed on the page if exceeded.

One point to note: this plugin’s methodology differs from ZCode. ZCode’s computedTotalTokens is input + cache + output, whereas this plugin prioritizes usage.totalTokens, then falls back to input + output, so the values may differ. Additionally, ZCode defaults to keeping 30 days of raw usage details, while this plugin retains a lifetime total, using only “the last 400 days” of daily granularity details for the heatmap and trend charts.

Caching and Performance¶

1. The summary result for each session is cached in <profile>/plugin-state/usage-stats-cache.json; entries for deleted sessions are retained with retiredAt, so the cache does not immediately expand after deleting a session, only growing slowly.

2. Subsequent scans are performed incrementally based on the persisted revision; only sessions that have changed are re-read. revision is the official change marker provided by DSH for derived caches.

3. The cache is pre-warmed once 5 seconds after the plugin starts, so opening the page normally mostly results in cache hits.

4. Cache migration is automatic: v2 caches are upgraded in-place to v3 without a full re-read; only older or unknown version caches are discarded and rebuilt.

5. To reset everything to zero, simply delete the cache file mentioned above and refresh; the plugin will rebuild from the remaining session logs.

Installation and Enabling¶

The official installation command is as follows:

dsh plugin --profile desktop add https://github.com/ailawu0409/dsh-usage-stats

It also supports local package paths or your own branch address; just replace the URL:

dsh plugin --profile desktop add <package-path-or-repo-url>

During local development, you can link the package directory directly into the profile:

dsh plugin --profile desktop add /path/to/dsh-usage-stats

After installation, restart DeepSeek Harness and go to Settings → Usage Statistics. To use the plugin’s custom navigation icon, DSH 0.2.2-rc.1 or a newer version is recommended; older hosts will fall back to the default gear icon.

Typical Usage¶

Once installed, configuration usually doesn’t need to be touched; daily use consists of just two things.

1. Open Settings → Usage Statistics to see the total tokens, daily peak, and longest session.
2. Manually refresh using the Refresh button in the bottom right corner; if it fails, a retryable banner appears at the top, and existing data is not affected.

If the numbers look wrong, troubleshoot in the following order: confirm the profile path where the cache file is located is correct → check the number of counted / no longer listed / skipped sessions indicated in the footer → delete the cache file and refresh to rebuild. Note that “counted sessions” being greater than “currently stored sessions” is a normal phenomenon because it includes deleted sessions that are still on the books.

To start from scratch (e.g., after changing machines and not wanting to carry over old history), delete <profile>/plugin-state/usage-stats-cache.json and refresh; the plugin will only rebuild from the session logs that still exist.

Applicable Scenarios and Notes¶

Suitable for local DSH users who want to look back at their token cost distribution and distinguish usage between different models, especially in scenarios where multiple models are used for long chains and it is necessary to determine which model takes the largest share.

A few points to note:

• The plugin runs with the permissions of the current DSH process. Before installation, you should check the source code and license (MIT) yourself; do not treat it as an official component.
• This is an unofficial plugin. The DSH extension API may change between versions, so re-verification is needed after upgrading the host.
• Deleting sessions does not reduce the historical total. If you need a true “current state” view, this plugin does not provide that.
• The statistics are capped at 20,000 sessions. On narrow panels, the heatmap reduces the number of weeks instead of scaling cells, so a narrow panel cannot display a full year.
• The “Last 7 days” trend actually draws 8 points (today plus the previous 7 days), consistent with the reference design.
• DSH 0.2.2 added interfaces in German, Spanish, French, Japanese, Portuguese, and Russian; this plugin’s text remains bilingual (Chinese/English), falling back to English for other languages.

Directory Page and Source Code¶

Directory page: https://www.skillhub.cn/plugins/ailawu0409/dsh-usage-stats
Source code: https://github.com/ailawu0409/dsh-usage-stats

It should be noted that the directory page is an independent community site with no official affiliation to DeepSeek / Fangfang, and is not an official app store.