Introduction¶

DeepSeek Harness (DSH) is built around the core idea of “everything is a plugin.” When developing or debugging with DSH, tracking token consumption is a common requirement. dsh-token-heatmap provides an intuitive monitoring view, displaying usage in a GitHub-style contribution graph.

Plugin Overview¶

This is a draggable floating window that displays the token usage of DeepSeek Harness. It is based on local session logs and makes no network requests or telemetry calls. It was developed by cccchensy and is licensed under MIT.

Key Features¶

• GitHub-style heatmap: Shows the total for today at the top and usage over the last 30 days below.
• Annual panel: Expands on hover to an annual panel showing total usage, active days, daily average, current and longest streak, best single day, and daily input/cache/output breakdowns.
• Draggable window: Can be dragged to any position; the position is remembered.
• Running-status indicator: Slowly blinks when a session is running.
• Local statistics: Reads session logs directly, with no network requests; supports counting subagent usage (configurable).

Installation and Enablement¶

In any session, send the following command to the agent to install it:

github:cccchensy/dsh-token-heatmap

The plugin takes effect per profile. After installation, restart DSH to load it. To uninstall or update the plugin, use the Plugins page. After updating, you must restart DSH.

Usage¶

• Drag: Press and hold any part of the window to move it to another location on the screen.
• View details: Hover the mouse to expand the annual panel and view detailed input, cache, and output data.
• Collapse: Double-click the window to collapse it to the title bar.
• Status blink: When a session is running, the window slowly pulses, indicating activity rather than that tokens are being consumed at this exact moment.

Limitations and Notes¶

Because the plugin is based on log reading, there are the following differences in measurement and limitations:
* Statistical basis: The numbers are accurate up to the last committed step, rather than the last generated token.
* Official alignment: The measurement aligns with the official usage page but is lower by 0.25%. This is due to failed requests that are retried: the official side counts prompts already processed by the server, while Harness does not write the usage of failed attempts into logs.
* Data scope: It cannot access prompts that the server processed but that failed.
* Deduplication: When the same session history is copied into multiple logs (such as subagent snapshots or forks), it is counted only once, with fingerprint-based deduplication.
* Compaction summaries: The compaction summary itself is a billable call and is included in the statistics.
* Blink meaning: The blink indicates “a session is running,” not “tokens are being consumed right now.”
* Permissions and updates: The plugin runs with the permissions of the current dsh process. After updating the plugin, you must restart DSH.

Conclusion¶

dsh-token-heatmap is a lightweight local monitoring tool, ideal for developers who need to intuitively track token consumption. Its GitHub-style interface reduces cognitive load, and it runs entirely locally. For more details, see the plugin catalog or the GitHub repository.