Preface

DeepSeek Harness (dsh) builds model adaptation, tools, session logs, and the UI all as plugins. In daily use, token consumption is tangible: the default interface does not centrally display how many tokens have been used today, which models accounted for the majority in the past week, or how many top-level conversations have been opened. You can calculate these numbers by flipping through session logs yourself, but the event fields are scattered and sub-agent sessions are mixed in, making it hard to see the totals at a glance.

The community plugin dsh-token-monitor turns this into a “Today’s Usage” card at the bottom of the sidebar: the numbers stay visible, and clicking it brings up a full dashboard. This article is organized after cross-checking the community directory page, GitHub repository README, package.json, and the host source code: what it is, what the current version actually displays, how to install it, and where the data comes from.

What It Is

dsh-token-monitor is a conversation and messaging plugin for the DeepSeek Harness web interface, maintained by zhangzheng25. Its repository is at zhangzheng25/dsh-token-monitor, with an MIT license, and its primary language is JavaScript. At the time of writing, the version in package.json is 0.6.0, and the repository has 5 stars on GitHub; the community directory page still shows 4 stars, and it is categorized under “Conversation and Messaging”.

It solves the problem of local usage visibility, rather than pulling account balances from official billing APIs. The current implementation (as of main commit a627daf on 2026-08-16) is:
- Place a “Today’s Usage” card at the bottom of the sidebar, next to the settings icon, showing the total tokens used today in a single line
- Clicking the card pops up a “Token Usage” window: total usage for today / past 7 days / past 30 days, a stacked bar chart of model usage over the past 30 days, a ranking of the top 4 models, and the number of top-level conversations during the corresponding period
- Usage is only backfilled from session logs, and historical data before installation will also be counted

One source discrepancy needs to be clarified first. The community directory page and GitHub repository profile still mention “Settings → Token Usage” and a GitHub-style 90-day contribution graph. That is the copy from earlier versions. The repository README and client/bundle.js have been updated to use a sidebar card plus popup window, and no longer register a settings page. The chart has also been changed to a 30-day stacked view colored by model, instead of a 90-day contribution heatmap. The following content is based on the current source code of the repository.

The official DeepSeek Harness repository positions itself as “everything is a plugin”, and the community plugin directory is an independent site with no affiliation to DeepSeek / Huanqiu, and should not be treated as an official app store.

Core Features

The client mounts the card to the sidebar.footer.action slot, located below the conversation list and next to the settings gear icon. When the sidebar is expanded, it displays “Today’s Usage: ” plus the numerical value; when collapsed into a narrow ~56px bar, only the number is shown.

The card requests the host’s /token-monitor/today every 30 seconds. This route reads the in-memory “today” bucket in a read-only manner, without triggering a full rebuild, so the sidebar polling is relatively lightweight. The total daily tokens are calculated by adding together input, output, cache hit, and cache write tokens. Reasoning tokens are written to daily buckets but are not included in the total numbers on this card or the popup window.

The numerical format switches based on magnitude: over 10,000 uses “ten thousand”, over 100 million uses “hundred million”, and larger values use B / T. The sample copy in the README is “Today’s Usage: 88.88 million”.

Totals and Conversation Cards in the Popup

Clicking the card brings up a fixed masked popup titled “Token Usage”, which can be closed with Esc, the ✕ in the top-right corner, or by clicking the mask. Scrolling in the background is locked when the popup is open. The panel starts with three total usage cards:
- Today’s Tokens
- Tokens in the Past 7 Days
- Tokens in the Past 30 Days

Below that are three conversation cards: the number of top-level conversations opened today, in the past 7 days, and in the past 30 days. The subtitle text is the number of model requests during the corresponding period. Internal sub-agent sessions (delegationDepth !== 0) are not counted towards the conversation count to avoid inflating the numbers from a single delegation.

There are also two buttons in the header: “Refresh” and “Backfill History”, along with the text “Statistics since … · History backfilled to …”. After the popup is opened, it pulls data from /token-monitor/snapshot, and then polls every 30 seconds afterward.

30-Day Model Stacked Chart

The chart uses a fixed 30-day window. Each day has a single bar, stacked by model with different colors; the model with the highest daily usage is at the bottom of the bar, and colors are fixed based on the total 30-day usage ranking, using a set of Morandi color palettes. The horizontal axis only marks the dates of each Monday. Hovering or clicking a day will pin a detail card: the date, total usage, and rows for each model’s color block. There are no numbers on the bars, and no grayed-out highlights.

When there is no data, the interface prompts: “No model usage data yet – after upgrading the plugin, click ‘Backfill History’ once to populate.”

Top Model Usage Ranking

The ranking is also locked to the 30-day window, taking the top 4 models and arranging them into a 2×2 grid of cards. Each card contains: a row for the ranking number, the model name plus total tokens, the provider plus usage percentage. The percentage is calculated client-side by dividing the model’s total usage by the total 30-day usage across all models. The cards do not show growth rates, or labels like “Total” or “New”.

The model identity is taken from the provider and model fields in message.source of the conversation event, combined into provider:model. If fields are missing, it is recorded as unknown.

Session Log Backfill and Local Persistence

The host-side code is mostly in src/index.js. v3 uses conversation logs as the sole data source: list sessions via sessionQuery, read events, only aggregate usage (input / output / cache hit / cache miss / reasoning) on assistant/message, and bucket by day and by model. sessionQuery prefers live data, including in-memory active sessions and persisted logs, so there is no need to attach a real-time llm/stream hook. The README notes that the old version’s “real-time stream capture + log backfill” would count the same call twice, and v3 has removed the real-time path: each run folds the window’s data into a new Map and then atomically replaces the old data, so repeated runs will not cause double-counting.

Backfill is triggered at these times: ~3 seconds after startup, when “Backfill History” is clicked, and when the snapshot polling has ?backfill=1. Full folding is throttled to 20 seconds, and only one run will execute at the same time.

The persistence file is $DSH_HOME/plugins/token-monitor/data.json (or ~/.dsh/plugins/token-monitor/data.json if DSH_HOME is not set), with schema version 3, retaining daily buckets for 181 days. If the old path $DSH_HOME/plugins/token-usage/data.json still exists, the first load will attempt to migrate data from it.

Installation and Activation

The installation command given on the community directory page, run in the DeepSeek Harness terminal:

dsh plugin add github:zhangzheng25/dsh-token-monitor

The repository README additionally notes that this is a web-side plugin (dsh.client.platform in package.json is "web"), and recommends explicitly specifying the web profile:

dsh plugin --profile web add github:zhangzheng25/dsh-token-monitor

You can also install from a local directory:

dsh plugin --profile web add /path/to/dsh-token-monitor

For reproducible installations, the directory page recommends pinning the commit hash. At the time of writing, the latest main commit is a627daf (2026-08-16, corresponding to the 0.6.0 sidebar card update):

dsh plugin --profile web add github:zhangzheng25/dsh-token-monitor#a627daf46e6ac822445e882353f70a8a81c2420a

dsh plugin will hand the installation to pnpm in the profile directory, and reconcile dsh.profile.bundles. The package’s cordis.patch.yml inserts the plugin line with id token-monitor into the host composition, rather than an agent preset – it needs to access the host’s sessionQuery, timer, and webServer.

You need to restart DSH after installation. The official way to start the Web UI is:

npx @deepseek-ai/dsh web

The default address is http://127.0.0.1:3080. After restarting, the “Today’s Usage” card should appear at the bottom of the sidebar; clicking the card will bring up the statistics window. package.json requires Node.js >= 20. DeepSeek Harness itself is still in developer preview, and the official README notes that breaking compatibility changes may occur.

Typical Usage

  1. Confirm that you are running the web interface, not a headless one-off run. The plugin’s client bundle is only loaded for the web shell.
  2. Install as per the previous section and restart. If the card does not appear, first check if the profile is web and if the token-monitor plugin has been inserted into the host composition.
  3. Check if the sidebar number is updating. Active calls will be included in the conversation corpus, but the card polls every 30 seconds, so do not expect every token to update immediately.
  4. Open the popup. If the stacked chart is empty, click “Backfill History” once and wait for the next snapshot. Old buckets may be discarded after an upgrade, and the source code comments note that when migrating from v1/v2 to v3, the data will be cleared and rebuilt from the conversation logs.
  5. Use the 30-day ranking to cross-check the model names you are actually using. The percentage only reflects the usage structure in the local conversation logs, not the official bill.
  6. To verify the raw numbers, open $DSH_HOME/plugins/token-monitor/data.json. It contains buckets grouped by day and model, not billing details.

Applicable Scenarios and Notes

It is suitable for these situations:
- Running the DSH Web UI long-term, and wanting to see today’s token count directly in the sidebar
- Switching between multiple models in the same environment, and wanting to see which model used the most resources over the past 30 days
- Care about the number of top-level conversations, excluding internal sub-agent sessions
- Installing the plugin late, but still wanting to count session logs from before installation

Before using, please note the following points, all from the directory page, repository instructions, or source code, not additional commentary:
1. The plugin runs with the permissions of the current dsh process. The community directory page notes that code may be executed during installation. You should review the source code repository and license before installing; for reproducible installations, pin the commit hash.
2. It only counts local conversation data, does not check account balances, and does not convert usage to costs based on unit prices. It is not the same type of plugin as those that use DeepSeek’s official usage API or specialized expense ledgers.
3. It only serves the web interface. dsh.client.platform is "web", and headless workflows will not see this card.
4. The interface total does not include reasoning tokens. There is a reasoningTokens field in the buckets, and the totals used on the card and ranking are input + output + cache read/write tokens.
5. Only top-level conversations are counted. Only sessions with delegationDepth === 0 are included; internal sub-agent sessions are excluded.
6. The repository includes an AI-generated disclaimer. The README notes that the project was generated with AI assistance, for learning and technical communication only, and does not constitute a commercial guarantee or support commitment. The license is MIT, with the copyright page marked Copyright (c) 2026 zhangzheng25.
7. Directory page copy may be outdated. If you still see “Settings page / 90-day contribution graph”, refer to the repository README and the current main branch instead.

Summary

dsh-token-monitor turns token usage and top-level conversation statistics into a card in the DSH web sidebar: today’s numbers are always visible, and clicking opens a window showing 7-day / 30-day totals, a model-stacked chart, and a top 4 ranking. The data is only idempotently backfilled from conversation logs, and usage before plugin installation can also be counted. After restarting, the data is stored locally in data.json. It does not replace official billing statements, only solves the problem of clearly seeing “exactly how much Harness on this machine has been used”.

Directory and repository links:
- Community Directory: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-token-monitor/
- GitHub: https://github.com/zhangzheng25/dsh-token-monitor
- DeepSeek Harness: https://github.com/deepseek-ai/deepseek-harness