dsh-plugin-token-usage
QwenPaw-style cross-session token usage statistics for DSH.
The plugin aggregates the provider-reported token usage of every model call
across all persisted sessions (including subagent sessions) into
(date, provider, model) buckets and serves them through a single /usage
command.
- Zero runtime dependencies — only the Cordis
ctx API and Node 22's
built-in node:zlib (zstd) are used.
- Durable source of truth — it reads the session logs under
~/.dsh/sessions, so it works on history that predates the plugin and needs
no separate bookkeeping at write time.
- No double counting — a committed
assistant/message.usage wins; a step
that never produced a message (failure) falls back to its last streaming
usage chunk, flushed at turn/end. A persisted per-file watermark
({hiSeq, framesIngested}) makes the incremental scan idempotent across
restarts and crash-recovery re-encodes.
Command
/usage # last 30 days (configurable defaultDays)
/usage 7d # last 7 days
/usage 7d qwen3.8 # last 7 days, model filter (substring on provider/model)
/usage qwen3.6 # default range, model filter
Example output:
📊 Token Usage 2026-07-17 → 2026-08-16
Total: 906.9M tokens · 4954 calls
input 473.3M · output 3.4M · cache read 430.1M
By model:
sglang/Qwen3.8-27B — 719.4M tokens · 3320 calls
in 337.7M · out 2.8M · cacheR 378.9M
sglang/Qwen3.6-27B — 187.4M tokens · 1634 calls
in 135.6M · out 669900 · cacheR 51.2M
By day:
2026-08-13 42.6M tokens · 481 calls
2026-08-14 195.7M tokens · 1587 calls
2026-08-15 380.5M tokens · 1513 calls
2026-08-16 288.1M tokens · 1373 calls
Token units: 1.2M for >= 1,000,000 (million), 1.5B for >= 1,000,000,000
(billion), plain integer below (one decimal, trailing .0 dropped).
Config
| key | default | description |
|---|
defaultDays | 30 | lookback window for a bare /usage. |
backfillIntervalSec | 30 | seconds between incremental backfill passes (keeps the state file warm). |
sessionsRoot | ~/.dsh/sessions | DSH session-log root (empty = auto from DSH_HOME). |
stateFile | ~/.dsh/token-usage.json | aggregated state + watermark. |
flushDelayMs | 5000 | debounce for the state write. |
enableCommand | true | register /usage. |
verbose | false | log backfill progress. |
Mounting
The plugin is an out-of-tree module mounted through a profile patch (same
pattern as the telegram / thinking-mode plugins). Add an insert row to
~/.dsh/profiles/web/cordis.patch.yml:
- insert:
- id: token-usage
name: '/home/lovedheart/Documents/dsh-plugin-token-usage/lib/index.js'
config:
defaultDays: 30
backfillIntervalSec: 30
enableCommand: true
verbose: true
commands is an optional dependency (consumed via an optional child
fiber), so the plugin also loads in command-less assemblies — it just stores
without registering the interactive command.
Layout
src/frames.js — zstd frame scanner (mirrors DSH's scanZstdFrames).src/store.js — bucket aggregation, dedup, persistence, summarize.src/backfill.js — incremental session-log walk + listSessionFiles.src/render.js — fmtTokens, renderUsageReport, parseUsageArgs.src/index.js — plugin entry (name/inject/Config/apply).lib/ — build output (npm run prepare copies src/*.js).test/ — node --test unit + harness tests.
Development
npm install # installs the cordis peer for the harness test
npm test # node --test test/*.test.mjs
npm run prepare # sync lib/ from src/
