Foreword

The philosophy of DSH is “everything is a plugin,” where the capabilities of the Web interface can be supplemented by plugins on demand. However, for daily users of dsh web, token usage data is scattered across event logs in various sessions, and there is no ready-made entry point to answer questions like “How much was used today?” or “How much total was used this month?”

Below is an introduction to @kidli1412/dsh-token-heatmap, a DSH Web GUI plugin: it renders a GitHub-style daily token usage heatmap below the input box on the new session screen. It provides three statistics—Today / This Month / Total—in the same row, and is ready to use upon installation.

What is This

One-sentence positioning: It displays a daily token usage heatmap and usage statistics for the current natural year (optional year) below the input box on the new session screen.

Maintained by KIDLi1412, licensed under MIT, and currently version 0.1.5. It runs on @deepseek-ai/dsh >= 0.1.2-alpha.4 (version 0.1.2 line). It solves the problem of aggregating token usage samples from session logs by day into a heatmap that can be read at a glance.

Core Features

Heatmap Card

After installation, a statistics card appears directly below the input box on the new session (hero) screen. Note that it only displays on the new session screen; conversations that have already been initiated do not display this card.

  • Natural Year View: Covers January–December of the selected year. The ‘‹ Year ›’ selector allows switching years, up to the current year.
  • Layout Aligned with GitHub: Columns represent weeks (starting Monday), rows represent days of the week. The left side labels all 7 days from Day 1 to Day 7. Dates after today are displayed as empty spaces.

Color Scheme & Grading

  • Six Color Schemes: Green / Blue / Orange / Red / Purple / Cyan. Switchable in Settings → Plugins → Plugin Configuration. Previewing the six color palette buttons is done in real-time.
  • Grading by Absolute Thresholds: 0 / <1M / 1M–10M / 10M–100M / ≥100M, totaling 5 levels. Hovering over the legend displays the range for each level, and hovering over a cell displays the date and the exact token count.

Statistics Row & Refresh

  • Statistics Row: The statistics row is on the same line as the title, displaying Today / This Month / Total. Hovering displays the full values.
  • Auto-refresh: Refreshes automatically every 5 minutes, or when the window becomes visible again. A manual refresh button is available at the end of the row.

Configuration

The plugin configuration card (Settings → Plugins → Plugin Configuration) provides a toggle for ‘Show Heatmap’ and a color scheme selection. You can save or discard changes after modification. The configuration is persisted to <DSH_HOME>/settings.yaml under the token-heatmap settings namespace; old configuration files from version 0.1.1 and earlier are automatically migrated upon startup.

Where the Data Comes From

The server-side incrementally aggregates token usage samples from all session event logs, grouping them by day and by model. It is cached in <DSH_HOME>/storages/token-heatmap-cache.json and served via the loopback restricted endpoint GET /api/token-heatmap/usage. The data endpoint is only accessible to loopback addresses, and credentials are not sent out; the plugin is read-only and does not modify any session data.

The implementation of the aggregation and loopback endpoint references dsh-usage-stats (MIT © Ychris12138).

Installation and Enablement

Prerequisites: You need the web profile and pnpm.

  1. Install from npm:
dsh plugin --profile web add @kidli1412/dsh-token-heatmap

You can also install from GitHub:

dsh plugin --profile web add github:KIDLi1412/dsh-token-heatmap

For local development, use a local link:

dsh plugin --profile web add "link:path/to/dsh-token-heatmap"

  1. After installation, restart the running dsh web and perform a hard refresh in the browser (Ctrl+Shift+R). This is necessary because both the server-side and client-side components load when dsh web starts.

  2. There is no new entry point in the sidebar. Open a new session, and the statistics card will appear directly below the input box.

Uninstall:

dsh plugin --profile web remove @kidli1412/dsh-token-heatmap

Compatibility

  • DSH: The manifest declares versions 0.1.2-alpha.4 / 0.1.2-alpha.5 / 0.1.2-rc.1 as compatible one by one; the host requires engines.dsh: ^0.1.2-rc.1.
  • Node: ^22.19.0 || >=24.0.0.

Use Cases and Notes

Suitable for users who use dsh web daily and want to intuitively grasp daily token usage: it does not change any interaction flow, and you can see the usage distribution immediately upon opening a new session.

Notes before use:

  1. The plugin runs with the permissions of the current dsh process; it is recommended to check the source code and license before installing.
  2. The statistics card does not render when there is no session or no workspace (the input.dock requires session context).
  3. After modifying the configuration, save or discard it on the settings page; the configuration is persisted in <DSH_HOME>/settings.yaml.
  4. You need to restart dsh web after adding or updating a plugin.

Closing

dsh-token-heatmap aggregates the scattered token usage from session logs into a familiar GitHub heatmap view. Combined with Today / This Month / Total statistics and switchable color schemes, it is a Web plugin that is ready to stay mounted for the long term.

  • Community Directory Page: https://www.skillhub.cn/plugins/KIDLi1412/dsh-token-heatmap
  • GitHub Repository: https://github.com/KIDLi1412/dsh-token-heatmap

The community directory site skillhub.cn is an independent site and has no official affiliation with DeepSeek or Huaquan.