Introduction¶

When running agents with DSH, session logs fall under $DSH_HOME/sessions, and token consumption is scattered across individual sessions. To answer questions like “How many tokens were used daily this month?” or “Which model is used the most?”, you have to manually decompress zstd-compressed JSONL, calculate them one by one, and write a script. Writing a script is not difficult, but you have to run it every time you check.

@kelearns/dsh-token-usage brings this into the GUI: a GitHub-style contribution heatmap showing daily, weekly, and cumulative token consumption. DSH’s philosophy is “everything is a plugin,” and this plugin is mounted via the official plugin mechanism without needing to modify the dsh source code. Below is an introduction to its features, installation method, and data metrics.

What is it¶

@kelearns/dsh-token-usage is a Token Usage Heatmap plugin for the DeepSeek Harness (dsh) web GUI, maintained by KeLearns, current version 0.1.1, MIT license. After installation, a “Token Activity” entry appears in the dsh settings sidebar; clicking it opens the heatmap.

It solves the problem: seeing token consumption trends and composition directly in the dsh interface without writing scripts or touching the source code.

Core Features¶

• Summary Bubble: A single rounded container holding 5 statistics—Total, Peak Day, Longest Session, Current Streak, Longest Streak—separated by vertical lines.
• Three Views: Daily (color-coded by day), Weekly (stacked by week), Cumulative (stacked cumulatively by week, the latest column is always full).
• Time Window Switching: Last 3 / 6 / 12 months, default 12; the 12-month view scrolls horizontally, auto-scrolling to the latest week.
• Hover Details: Hovering over a cell displays the daily total, weekly total, or cumulative total up to that day; zh / en localization.
• Activity Insights: Most used model / Reasoning intensity / Tools, peak hours, daily and monthly averages, most active workday and most active day.
• i18n: zh / en, following the document language in real-time.
• Theme: Light / Dark color palettes, following the dsh application theme.
• Auto-refresh: Rescans changed session files every 60 seconds and when the window is focused.
• Cross-platform: The host side only uses Node standard libraries (fs / path / os / zlib), supporting Windows / macOS / Linux.

Installation and Enablement¶

The prerequisite is that pnpm is in the PATH:

npm install -g pnpm

Install from npm (Recommended):

dsh plugin --profile web add @kelearns/dsh-token-usage

The installer reads cordis.patch.yml (dsh.bundle.patch manifest fields) and automatically applies the plugin line; no need to manually edit the patch file. Restart dsh web after installation to take effect.

For local development, run it in the plugin repository root directory; link:. resolves to the current directory:

dsh plugin --profile web add link:.

Uninstall:

dsh plugin --profile web remove @kelearns/dsh-token-usage

You can also install manually without using the CLI, in three steps:

1. Put the package into $DSH_HOME/profiles/web/node_modules/@kelearns/dsh-token-usage;
2. Append the following insert block to $DSH_HOME/cordis.patch.yml (can be run repeatedly):

- insert:
    - id: dsh-token-usage
      name: '@kelearns/dsh-token-usage'

3. Restart dsh web.

This plugin is included in the awesome-dsh-plugin curated registry, and can also be installed by searching for token-usage in the Plugin Market tab of dsh settings.

Data Source and Metrics¶

The plugin reads dsh official session logs: $DSH_HOME/sessions/<workspace>/<session-id>/session.jsonl.zstd, which is JSONL with concatenated zstd frames. Token usage is calculated from records where chunk.type === "usage" in the assistant/chunk event; Total = input + output + cacheRead. Activity Insights also reads request/header (model / reasoning intensity) and tool/call (tools) events.

A few metrics need to be known first:

1. Only sessions carrying usage events are counted (dsh session log format, verified on 0.1.0-rc.6);
2. Dates are attributed to the process’s local timezone; weeks start on Monday;
3. zstd decompression requires Node >= 22.2 (package engines is ^22.19.0 || >=24.0.0, official dsh runtime satisfies this);
4. Missing or unreadable session directories return empty statistics and do not affect the GUI.

Configuration and HTTP Interface¶

Configuration has only one item refreshIntervalMinutes, controlling the background rescan interval (minutes), default 5. Just add config to the insert block in cordis.patch.yml:

- insert:
    - id: dsh-token-usage
      name: '@kelearns/dsh-token-usage'
      config:
        refreshIntervalMinutes: 5   # Background rescan interval, default 5

The plugin registers three same-origin HTTP routes:

Testing¶

The repository comes with three test scripts covering different levels:

node test/mock.test.mjs                            # Full pipeline with synthetic data
node test/mock.test.mjs "$env:USERPROFILE\.dsh"    # Smoke test with real data (any DSH_HOME)
node test/layout-algo.mjs                          # Layout algorithm matrix

The second line can point to any DSH_HOME for smoke testing with your own session data.

Use Cases and Considerations¶

Suitable for people already using the dsh web GUI who want to see token consumption trends and composition directly in the interface. If you run sessions with dsh open every day, this heatmap can answer questions like “How many tokens used today?”, “What are the trends in the last few weeks?”, and “Which model is used the most?”.

Before installation, there are two points to note:

1. The plugin runs with the permissions of the current dsh process; it is recommended to review the source code and license (MIT) before installing to confirm you accept it;
2. The session log format has been verified on 0.1.0-rc.6; if your dsh version differs significantly, run the test scripts mentioned above first to confirm parsing works correctly.

Summary¶

@kelearns/dsh-token-usage brings scattered token data from session logs into the dsh interface: one installation command, and after restarting, you can see the daily / weekly / cumulative consumption heatmap and activity insights without maintaining your own parsing script. Install and restart following the steps above, and “Token Activity” in the settings sidebar is your entry point.

Project address and listing page:

• GitHub: https://github.com/KeLearns/dsh-token-usage
• Community Directory: https://www.skillhub.cn/plugins/KeLearns/dsh-token-usage

The community directory is an independent site and has no official affiliation with DeepSeek / Inception.