dsh-desktop-token-usage

English | 中文 | 繁體中文（臺灣） | 繁體中文（香港） | Deutsch | Français | Español | Italiano | 日本語 | 한국어

A fully offline token usage statistics plugin for DSH (DeepSeek Harness).

• The Host half scans $DSH_HOME/sessions/**/session.vN.jsonl.zstd and folds out the real token usage;
• The Client half mounts a usage card at the foot of the left sidebar; clicking it opens a dashboard in the central
  panel: time-range and source filters, 6 stat cards, a configured-windows row, an activity heatmap, a per-day token
  trend (a cache hit-rate curve overlaid on the token bars, real percentages labelled on the right, its Y axis padded
  10% beyond the period's min/max), and a model usage donut chart with a list.

Which time spans the card and the dashboard's Configured windows row report is decided by the plugin
configuration (both windows are off by default): in Settings → Plugins → Token 用量 (Token usage) you can
enable a "last N hours" window (0-23) and a "last N days" window (1-30) independently; turn both off and each surface
falls back to a single cumulative block.
Those windows are wall-clock recency and deliberately ignore the dashboard's source filter, so they sit in a row of
their own rather than among the filter-following stat cards.
The same settings page also picks the grouping — by model, by provider, or both (with both, the trend section
and the breakdown section, 用量拆分, each get a switchable chip) — and the color palette — primer, cvd or muted,
each with a light and a dark set that follows DSH's own light/dark switch (body[data-ds-dark-theme]), so the
charts never disagree with the shell.

The sidebar foot is one horizontal row shared with every other plugin registered there, and every one of them declares
width: 100% — so no two of them can share it. Measured live, with nothing intervening this card is squeezed to
105.2px. The card therefore turns that row into a column ([class*="_footerActions"]:has(.dtu-footCard) — keyed on
the class suffix plus :has(), so nothing depends on DSH's hashed class names and no ancestor is touched), which gives
each plugin in the seat the full-width line it was written for; this card spans the whole 256px. It is flex-direction
rather than flex-wrap because the shell wraps each slot in a display: contents element — a direct-child selector
never matches the seat — and because on a column seat flex-wrap means "start another column", which pushes the card
beside its neighbour instead. That needs :has(); see the compatibility table below.

No network access, no telemetry, no API calls: every number comes from session logs that are already on your machine.

Screenshots

Rendered from this plugin's own components with sample data — the shots are produced offline by
scripts/render-shots.mjs (the real client.js and CSS against a fake Host) plus
scripts/render-shots.py (headless Chrome), so no session logs, paths or account
details are involved. Light theme first, dark theme second. The shots are rendered in Chinese — the first script takes
--locale to render another language — and all ten language variants of this README share the same set.

Six stat cards, the configured-windows row, the activity heatmap, the per-day token trend with the cache hit-rate
curve overlaid on the bars, and the model usage breakdown.

The same dashboard on the dark theme — each palette ships a light and a dark set.

The card at the foot of the sidebar shows the two configured windows; clicking it opens the dashboard above. The plugin's
page in the Plugins manager carries the window spans, the grouping and the palette.

Compatibility and tested environment

Fully verified on DSH Desktop 0.1.7-rc.2, 0.2.0-rc.2 and 0.2.1-rc.2; checked for compatibility with 0.2.0-rc.1.

Verification went well beyond "it installs": plugin activation reaching fiberPhase: active, the sidebar card and the
central dashboard rendering, the config card that the plugin page carries being readable and writable, the
browser → Host Remote calls working end to end, and every field matching DSH's own projection cache in a cross-check.

For 0.2.0-rc.1 the check was structural rather than a second full run. Every published package this plugin touches
was diffed against 0.1.7-rc.2: dsh-plugin-manager is byte-identical, and in dsh-client-ui-sidebar,
dsh-client-ui-layout and dsh-client-ui-cordis only the version string, one analytics call and title-bar CSS differ.
The sidebar.footer.action slot contract and its { wide } owner props are unchanged, and the packages this plugin
imports (dsh-api-remotes, dsh-client-ui-layout, dsh-client-ui-sidebar) keep their names. A manual trial on
0.2.0-rc.1 reports the dashboard and the Remote calls working, and 0.2.0-rc.2 then got the full run on this plugin's
own development machine: activation reaching fiberPhase: active, the sidebar card and the dashboard issuing real
Remote calls (calls.json), and the windows in boot.json matching the profile.

This plugin declares no @deepseek-ai/dsh* peer dependency, and that is what DSH actually validates — an absent
peer range applies no version constraint at all. engines.dsh is declared as ^0.1.7-rc.2 || ^0.2.0-rc.1 for humans
only: the official documentation states plainly that declaring a range does not reject incompatible hosts.

Versions other than the table above are untested. Earlier DSH builds may lack the plugins.bundle.config slot and
the configEditor service this plugin uses (without them there is no config card, and configuration can only be edited
by hand in the profile patch); builds newer than 0.2.1-rc.2 have not been verified yet.

What it writes to disk

The plugin reads session logs and writes only inside one directory of its own:
$DSH_HOME/cache/dsh-desktop-token-usage/. Nothing is written next to a session log, nothing elsewhere under
$DSH_HOME is created, modified or deleted, and no network access is ever made.

Both writers are atomic: they write a ..tmp sibling and rename it over the target, so a concurrent
reader never sees a partial file and a killed process cannot leave a truncated one behind. The index is capped at 800
entries (oldest dropped, re-scanned on demand), and any .tmp a crash left behind is swept on the next write.

Installation

This repository is a DSH bundle (package.json declares dsh.bundle.patch and dsh.client). Install it through the
official entry point; no manual editing of profile files is needed. The package is published on the official npm
registry, so the package name alone is enough — the manager resolves it on the registry and installs it into the
current profile:

plugin_manager  action: install_bundle  target: dsh-desktop-token-usage

To install from a local checkout instead (for example to run an unreleased main), point install_bundle at this
directory's absolute path.

plugin_manager  action: install_bundle  target:

Because this package depends on @deepseek-ai/schemastery (the schema library the official Config card needs), and
install_bundle uses a link: install for local directories and does not install dependencies for linked
packages, install once inside this repository first:

npm install            # installs dev/runtime dependencies only, no network data

After editing the code: the client hot-reloads, the Host needs a restart

To tell which version is currently running: check whether $DSH_HOME/cache/dsh-desktop-token-usage/boot.json exists and
whether windows matches expectations.

Uninstall: plugin_manager action: remove_bundle target: dsh-desktop-token-usage.

> The package name and the plugin row id are two different things: the row id is dsh-desktop-token-usage (the anchor for
> configuration overrides in the profile), and the package name is dsh-desktop-token-usage. Use the package name
> to uninstall/install, and the row id to change configuration.

Usage

1. Look at the card at the bottom of the left sidebar, above Settings: it shows each window's input/output volume
   and cache hit rate according to your configuration;
2. Click it → the dashboard opens in the central panel;
3. At the top of the dashboard you can filter by time range (last 7/14/30/90 days, all, custom) and by source;
   a refresh button sits in the bottom-right corner.

Both filtering and aggregation happen in the Host: every change issues a fresh aggregation request to the Host (the
Host keeps an index cache keyed by file mtime+size, so warm calls are in the hundreds of milliseconds). The card
quietly refreshes once every 5 minutes — the hour window slides with the clock anyway, so it should update even when
there is no new usage.

How to read the activity heatmap

• It is a calendar (Monday-aligned, the last 53 weeks) with month and weekday axes; the cells share out
  the card's width, so they stretch with it and stay square (11px is the reference size);
• The color scale uses quartiles over non-zero days, not "day ÷ maximum" — with the latter, a single
  exceptionally large day presses everything else into the same shade of gray;
• The header toggles between Tokens / turns; the default is whichever dimension has more days with data (on a
  machine with a lot of imported history tokens are sparse, so drawing tokens by default would give an almost empty
  grid);
• It follows the source filter but is not affected by the time range: a calendar filtered down to 7 days would
  mean "7 lit cells in a year grid", which is exactly what a heatmap should not look like.

Localization

The dashboard follows DSH's own language setting. It has no language picker of its own: change the language in
DSH and the dashboard switches with it, immediately and without a reload.

• en and zh are DSH's built-in locales, and this plugin ships a dictionary for both;
• The following language packs are registered into DSH's catalog, so they appear in its own selector: zh-TW
  (臺灣正體), zh-HK (香港繁體), de, fr, es, it, ja and ko. The remaining six codes — pt-BR, ru,
  vi, th, id and ar (right-to-left) — are designed but not implemented yet; see
  the design;
• Copy lives in locales/.json, one flat file per language, and is generated into client.js by
  node scripts/build-dicts.mjs. Never edit the generated block by hand — npm test fails while it is stale;
• Numbers, percentages, dates, weekday and month names, and plural forms all come from Intl, so a language that
  groups thousands differently, writes 萬/億 where English writes K/M/B, or inflects its plurals reads
  correctly;
• translations/README-.md and translations/CHANGELOG-.md carry both documents in each of the ten languages. They stay in the
  repository for GitHub; npm shows README.md only.

Configuration

Edit these in the Plugins → Token 用量 page (Token usage) — the Plugins entry in the sidebar → Token 用量:
in the middle of the page the plugin draws its own card — the hours box, the days box, the grouping and palette
selects, and a save button.

DSH does not generate an editor automatically from the Config schema — a plugin that brings its own configuration
has to render the form into the plugins.bundle.config slot (addressed by package name). That is what this plugin
does: on save it calls the official configEditor, and the values end up in the profile's cordis.patch.yml, so you
can also write them there directly:

- id: dsh-desktop-token-usage
disabled: false
config:
hours: 6
days: 7

With both off (the default) the card shows cumulative values, just as before these two parameters existed. Windows
round to the hour in local time: "last 6 hours" means starting from the top of the hour 6 hours ago.

Changes take effect immediately after saving: Cordis's fiber.update() restarts this plugin's fiber and apply
runs again with the new configuration (so you never need to restart DSH to change a value); after saving, the form
re-reads the configuration and refreshes the card automatically.

Data semantics

This section matters — what the numbers mean is determined entirely by DSH's log semantics.

Fold semantics (an easy place to get the math wrong): within the same (turn, step), a later usage entry
replaces the earlier one — the streaming numbers are overwritten by the final settlement; only after
llm/retry-started closes the slot does another retry call accumulate. So "total = sum of all usage" is wrong; you
must fold. This plugin's folding logic corresponds line for line with the tokenUsage projection in
dsh-token-meter, and is covered by cross-check tests.

Why the source filter has only three options

DSH 0.1.7-rc.2's session logs have no "client source" field: SessionHeader carries only
version/id/createdAt/cwd/parentSession/isSeeded/origin/delegationDepth/agentPreset, and the only value origin
ever takes is 'subagent'. Desktop and web cannot be told apart from local data. The dashboard therefore offers only
the three options that are derivable from local signals:

Sessions with no user turn at all (for example, ones that only ran slash commands) count toward 全部 (all) and are
not listed separately.

Known limitations

• The first aggregation is slow: with roughly 150 session files and 90,000+ records, a cold start takes about
  3–4 seconds; after that it goes incremental by file fingerprint, with warm calls in the hundreds of milliseconds.
  The cache is written to $DSH_HOME/cache/dsh-desktop-token-usage/sessions-index.json; deleting it only makes the next run
  slower.
• Imported historical sessions may report zero usage: if a historical session was imported (a reasonix migration,
  for instance), its usage fields really are all 0. That is valid data, not missing data, and this plugin does not
  fall back to estimating it.
• Only ten languages are translated: the dashboard follows DSH's language setting, but its copy does not yet cover
  every language DSH can be set to; the Localization section above lists the six that are still missing.
• Windows round to the hour: the logs have no minute-level buckets, so "last 1 hour" aligns to the top of the
  hour.
• The card refreshes with a delay: there is no Host→Client push channel, so the card relies on a 5-minute silent
  refresh timer; if you just changed the configuration or want an update right away, click the card to open the
  dashboard and hit 刷新 (refresh).

Verification status

Verification completed so far (see the "verification evidence" section of docs/DESIGN.md):

• The folded result matches DSH's own projection cache field by field (session-5964a5d3-*: 286650 / 182633 / 43826560 / 0);
• Both the per-day and per-model summaries re-add to the total, and the per-day/per-hour millisecond ranges partition the total exactly;
• Card window summaries: every window can only be less than or equal to the cumulative value, the input/output split identity holds, and out-of-range parameters (hours=99/days=-3) are clamped;
• The Config schema validates through the Standard Schema interface: default 0/0, while hours=24 and days=31 are rejected;
• The Host descriptor and the Client contribution are cross-checked field by field in the tests, and the parameter codec accepts the values the browser actually sends;
• Both client halves render in a browserless environment with a fake React/DOM (covering both the card window row and the cumulative fallback), with assertions on style injection and unmounting;
• After installation, include:dsh-desktop-token-usage has fiberPhase = active, and dsh-desktop-token-usage shows up in both
  sidebar.footer.action and main (active: true);
• The browser → Host RPC path is proven to work (the Host-side index is rewritten after the page calls it).

Confirmed / still needs your confirmation:

1. The Host-side configuration path has been verified end to end: Config.listConfigs reports status: schema
   for this plugin (id: include:dsh-desktop-token-usage, name is the package name); after restarting the fiber, boot.json's
   windows equals the {hours:5, days:1} configured in the profile — both reading the configuration and writing it
   back through configEditor work correctly under the scoped package name.
2. The client still needs a hard page refresh (Ctrl/Cmd+Shift+R): the config card in the middle of the plugin page
   is registered by the client (plugins.bundle.config is keyed by package name), and a new client module has to
   be loaded before it appears.
3. The Host module generation still needs one restart: Node caches ESM by resolved realpath, so editing files — or
   even renaming the package — does not re-import it; in practice
   import('dsh-desktop-token-usage') === import('dsh-desktop-token-usage') is the same module instance. So new Host code
   such as the payload.heatmap the heatmap depends on can only be loaded by restarting; until then the client takes
   the "missing heatmap" fallback.
4. The dashboard's visuals (including the reworked heatmap) need your own eyes — this environment has no browser
   control.

Where to look when something breaks

Two self-diagnostic files live under $DSH_HOME/cache/dsh-desktop-token-usage/:

• boot.json: the Host activation chain (appliedAt/injectedAt/providedAt/registeredAt) and the active
  windows; if there is an error, it tells you which step stalled. Every apply rewrites it, so appliedAt is the
  time of the fiber's most recent remount; but it cannot prove you are running the latest code — editing files
  does not re-import modules, only a restart does.
• calls.json: the last 20 dashboard requests (filters, window, session count, total tokens, elapsed time).
  A record proves the browser → Host path works; no records does not by itself prove the path is broken (the file
  may simply have been deleted), so read it together with boot.json; if there has genuinely never been a record, the
  client module most likely never loaded — hard-refresh the page (Ctrl/Cmd+Shift+R).

Also, the status from Config.listConfigs tells you directly whether the current fiber's module exports Config:
absent = an old module generation (there will be no config card on the plugin page); schema = a schemastery
schema has been recognized (which is this plugin's case). Note that schema only means it can be validated; the
configuration UI is still rendered by the plugin itself into the plugin page (see "Configuration" above), and DSH will
not generate a form from the schema.
A client older than the Host causes problems too — which is why the client falls back to cumulative values when it
cannot get the card field, instead of sitting on "loading".

Development

npm install     # installs @deepseek-ai/schemastery (a link install does not install dependencies for linked packages)
npm test        # node --test: aggregation golden cross-check + window summaries + browserless client smoke tests

The tests also run apply, so when they write diagnostic files they point at a temporary directory
(DSH_TOKEN_USAGE_DIAG_DIR) and will not overwrite the two files you want to inspect under
$DSH_HOME/cache/dsh-desktop-token-usage/.

Layout:

index.js                     Host half: Config (schemastery) + registration of the usage Remote service
client.js                    Client half: window __ModuleLoader__ factory + dashboard and sidebar entry
lib/session-usage.js         Pure Node aggregation: multi-frame zstd reading, folding, hourly bucketing, window summaries, index cache
test/session-usage.test.mjs  Aggregation, millisecond ranges, card windows, calendar, Config schema, Remote service
test/client-smoke.test.mjs   Client factory / slot registration / two-half wire-contract cross-check / rendering
docs/DESIGN.md               Design, data contracts, pitfalls hit, and verification evidence
docs/research/               Earlier research notes and reusable session-log probe scripts
CHANGELOG.md                 Version history (with a commit index)
translations/                 The other nine languages' README and CHANGELOG

The docs come in ten languages: English is the default (README.md / CHANGELOG.md), and every other language has its
own translations/README-.md / translations/CHANGELOG-.md. All ten are cross-linked by the switcher on line 3 of each file.

License

MIT