dsh-plugin-token-usage

August 20, 2026 · View on GitHub

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/