Introduction

When running intelligent agent conversations with DSH (DeepSeek Harness), two questions often arise: how many tokens were actually consumed in this round, and how much context window remains. The default Web GUI only has Chat and Trajectory pages; these numbers are either invisible or require manually checking the raw logs.

samecorner/dsh-token-usage solves exactly this: it is a client-side plugin that adds a “Token Usage” page to the top tab bar of the session (after Chat / Trajectory), directly displaying the token breakdown for the entire conversation and context usage. Below is an introduction to its features, installation methods, and considerations regarding data metrics.

What is it

dsh-token-usage is a Token Usage Analysis plugin for the DSH Web GUI. The npm package name is @samecorner/dsh-client-ui-token-usage, current version 0.1.3, MIT licensed, and maintained by samecorner.

Its approach is: the host-side token-meter and session-stats modules are built into DSH web and continuously produce projection data such as tokenUsage, contextPressure, contextBreakdown, and sessionStats; the plugin registers a conversation.view slot entry on the client side to render these projection data into visual panels. Per-turn level data is obtained by the plugin client by folding assistant/message usage from the session event window.

The author mentions in the README that it is inspired by pi-web-token-usage (a similar plugin for pi-web), but it has been completely reimplemented according to DSH’s plugin contract.

Core Features

Categorized by data source, the plugin provides the following sections:

  1. Full-round KPIs. Four cards for Total Token / Billed Token / Output / Cache Read, featuring number rolling animations, data sourced from the host-side tokenUsage projection.
  2. Context Pressure. Context usage progress bar, changing color with a warning when it reaches 80% or above; next to it are hints for cache hit rate, inference proportion, and average/peak per-call.
  3. Context Composition. Three stacked bars for System Prompt / Tool Schema / Conversation Content, reflecting the composition estimation of new requests, sourced from the host-side contextBreakdown projection.
  4. Turn and Step Statistics. Sourced from the host-side sessionStats projection.
  5. Composition Ring Chart and Detail Table. Split by Input / Cache Read / Cache Write / Output / Inference, each item with a percentage micro-bar.
  6. Per-turn View. Per-turn stacked bar chart (hover shows tooltip), per-turn details (including duration), cumulative billed curve, calculated by the client from the usage field in the session event window.
  7. Split by Model. Token count, call count, cache hit rate for each model.
  8. Utilities. One-click copy of Markdown report; “Load Earlier Records” button to browse older turns.

Installation & Enablement

Recommended for one-click installation via npm, no compilation or config changes required:

# Can be run anywhere; dsh will automatically run pnpm in the corresponding profile directory
# (Profile will be automatically initialized on first use)
dsh plugin --profile web add @samecorner/dsh-client-ui-token-usage

# Restart dsh web; the "Token Usage" tab will appear at the top

This package declares dsh.bundle.patch (corresponding to bundle.patch.yml inside the package), which will be auto-mounted after dsh plugin add: the package is added to the profile’s bundle layer, and there is no need to manually modify cordis.patch.yml.

One prerequisite to note: if you previously manually inserted an entry with the same ID in cordis.patch.yml, please delete it first, otherwise it will error due to duplicate mounting.

Updating and uninstalling are also one-command operations:

dsh plugin --profile web update @samecorner/dsh-client-ui-token-usage
dsh plugin --profile web remove @samecorner/dsh-client-ui-token-usage

When uninstalling, dependencies and layer lists are automatically removed along with it.

Source Build & Local Development

To modify code or debug locally, you can use source building:

# 1. Build (requires node >= 18; dependencies only from public npm packages, no DSH source code needed)
npm install
npm run build        # Produces lib/client.js + lib/index.js

# 2. Install into profile via local directory (same command, auto-mounts)
dsh plugin --profile web add /path/to/dsh-token-usage

# 3. Restart dsh web

Directory dependencies use link semantics: modifying code and running npm run build again, then restarting the web will take effect without the need to copy or sync files.

Common development commands:

npm run typecheck    # tsc --noEmit
npm run build        # esbuild: browser bundle + node half
npm run test         # smoke test: loader form + SSR rendering (web not started)

There is a hard requirement on the packaging format: lib/client.js must be wrapped with window.__ModuleLoader__.load({ id, factory }), while platform modules like react / cordis / ui-slots remain external. The runtime of this package is zero-dependency—package.json only contains devDependencies (types and build tools).

If you plan to write your own DSH client plugin, the docs/client-plugin-dev-guide.zh.md in the repository is a development guide covering the official Demo directory, full process, and a list of pitfalls.

Data Metrics & Known Limitations

Before looking at the numbers, clarify a few metrics to avoid misinterpretation:

  • Per-turn details only cover “assembled assistant/message within the window that have usage”. Cancelled steps and calls without usage will not appear in the per-turn table; the full-round total is based on the host projection, so there may be slight differences between the two metrics.
  • Inference tokens are counted as output, consistent with the token-meter metric.
  • There is no cost estimation. DSH does not record unit prices, so the plugin does not perform estimated billing.
  • Context usage displays the approximate projection of token-meter (projectedTokens / contextWindow), not the billing metric.

Applicable Scenarios & Notes

This plugin fits two scenarios: one is long-session development, where you need to monitor context usage and decide when to start a new session; the other is cost and efficiency optimization, such as verifying cache hit rates or comparing actual consumption across different models. The ability to copy the Markdown report also facilitates pasting usage data into issues or documentation for discussion.

Two reminders:

First, like all DSH plugins, it runs with the permissions of the current dsh process. It is recommended to check the source code (publicly available in the repository) and the license (MIT) before installing to ensure it is safe.

Second, the plugin depends on host-side projection data; the per-turn view depends on the usage field within the session event window. If certain calls lack usage, the corresponding row will not appear. This is not a plugin malfunction, but a metric limitation.

Conclusion

dsh-token-usage focuses on a specific task: transforming DSH’s built-in token projection data into an understandable analysis page. If you are using DSH web to run intelligent agent conversations, install it, restart, and you will have an extra “Token Usage” tab at the top, allowing you to directly answer questions like “How many tokens did this session consume and how much context is left?”

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

(The community directory is an independent site with no official affiliation to DeepSeek / Hypothesis.)