DSH Token Usage Heatmap

中文 | English

dsh-plugin-token-usage-heatmap is an out-of-tree bundle for DeepSeek Harness Web. It adds a GitHub/Codex-style token usage heatmap under Settings → Personal statistics without modifying the DSH source code.

Preview

Chinese UI

![Personal statistics page in Chinese](./assets/示例.png)

English UI

![Personal statistics page in English with a weekly tooltip](./assets/示例2.png)

Features

Shows total tokens, peak daily tokens, longest chat duration, current streak, and longest streak.
Provides daily, weekly, and cumulative views for the most recent 53 weeks.
Uses stronger colors or taller weekly bars as token usage increases.
Shows exact totals and input, output, cache-read, and cache-write details on mouse hover and keyboard focus.
Supports Chinese and English, light and dark themes, horizontal scrolling, and responsive layouts.
Derives statistics from existing session logs, so usage recorded before installation is included automatically.

Counting Rules

Data comes from persisted DSH session logs and currently active sessions. Main sessions, subagents, and workflow sessions are all included.
Usage follows DSH token-meter folding semantics: assistant/chunk usage is counted, while a final assistant/message usage sample replaces earlier samples from the same step to avoid double-counting.
A day's total is the sum of uncached input, output, cache-read, and cache-write tokens. Dates use the browser's IANA time zone.
Longest chat duration is the largest first-event-to-last-event span of any single session.
An empty current day does not immediately break the current streak. If the current day has usage, it is included in the streak.
Deleting a session removes its contribution on the next read. The plugin does not create or duplicate session events.

Compatibility

Item	Supported range
DeepSeek Harness	`>=0.1.0-rc.5 <0.2.0`
DSH profile	`web`
Node.js	Follows the requirements of the installed DSH version
Source build	Corepack; the repository pins pnpm 11.7.0
Direct GitHub installation	pnpm 10 or later

DSH 0.1.0-rc.5 has been verified in a running Host/Web environment. Installation, tests, type-checking, builds, and package checks have been verified against DSH 0.1.0-rc.6.

Clone and Install from GitHub

1. Clone the repository

git clone https://github.com/QuanWenG/token_usage_heatmap.git
cd token_usage_heatmap

2. Install dependencies and build

pnpm install
pnpm test
pnpm typecheck
pnpm build

3. Add the plugin to the DSH Web profile

If the dsh CLI is installed on your system, run the following commands from the plugin directory:

dsh plugin --profile web add .
dsh --profile web --dump-config
dsh --profile web

If you run DSH from a source checkout, switch to the DSH repository root and replace the example path with the absolute path of this cloned repository:

pnpm dsh plugin --profile web add /absolute/path/to/token_usage_heatmap
pnpm dsh --profile web --dump-config
pnpm dsh --profile web

Open http://127.0.0.1:3080, then go to Settings → Personal statistics. The --dump-config output should contain a # == dsh-plugin-token-usage-heatmap layer and a token-usage-heatmap plugin row.

The same commands work in Windows PowerShell; replace the example path with the actual absolute path.

Direct Installation from GitHub (Optional)

DSH can also add the GitHub repository directly to a profile. Pin a release, tag, or commit so later repository updates cannot silently change the installed code:

dsh plugin --profile web add github:QuanWenG/token_usage_heatmap#<tag-or-commit>

Git dependencies use this project's prepare script to generate lib/. pnpm 10 and later block dependency build scripts unless explicitly approved. If the first installation is rejected, copy the exact package key shown by DSH/pnpm into the profile's pnpm-workspace.yaml:

allowBuilds:
  dsh-plugin-token-usage-heatmap: true

Grant build permission only after confirming that you trust the source, then run the installation command again.

Configuration

Cold-session reads use a default concurrency of 4. Override the complete plugin configuration in the profile's cordis.patch.yml:

- id: token-usage-heatmap
  name: dsh-plugin-token-usage-heatmap
  config:
    maxConcurrentSessionReads: 4

The allowed range is 1–32. A later DSH patch replaces the complete config object rather than deep-merging it, so an override must retain every configuration key that is still required.

Update

Run the following commands in the cloned repository:

git pull --ff-only
pnpm install
pnpm test
pnpm build

Restart DSH Web afterward so the Host and browser bundles are reloaded.

Uninstall

dsh plugin --profile web remove dsh-plugin-token-usage-heatmap

When running DSH from source, replace dsh at the start of the command with pnpm dsh. Uninstallation removes only the bundle layer and profile dependency; there is no separate statistics database to clean up.

Development and Verification

pnpm test
pnpm typecheck
pnpm build
pnpm pack:check

Build output includes the Host bundle at lib/index.js, the browser bundle at lib/client.js in the window.__ModuleLoader__ factory format, inlined CSS Modules, and declarations under lib/types.

GitHub Actions runs installation, tests, type-checking, builds, and package checks on Node.js 22 and 24.

License

This project is licensed under the [MIT License](./LICENSE).