dsh-plugin-token-usage

dsh-plugin-token-usage

A DeepSeek Harness plugin that read-only scans your local session logs and renders a GitHub-style token usage heat map with a granularity-linked per-model breakdown — plus an instant "tokens today" badge on hover. Everything stays on your machine.

Compatibility: targets DSH 0.2.1-rc.2 through 0.2.x (verified on 0.2.1-rc.3). The tool run-card registers in the tool.call.toolview key domain under the wire tool name usage_report; the legacy tool.view.cordis/self slot is now owned by the dynamic Client Guard and no longer applies to static plugins.

Both session-log generations are supported: the old session.jsonl.zstd (assistant/chunk + chunk.usage) and the new session.v3.jsonl.zstd (assistant/message + data.usage, model attributed per message source). When both coexist in one session directory only the highest version is read, so no stretch of history is counted twice.

中文说明

Features

• 🔥 GitHub-style heat map: one cell per day for the last 30 days (zero-usage days filled), Sunday-first columns, month labels, today outlined; 5-level accent scale normalized per view.
• 🗓 Day / Week / Month switcher: weeks start on Sunday, aligned with grid columns; the color scale renormalizes per granularity.
• 🫧 First-party tooltips: 08-22 · 420M token · 341 requests · 95.9% cache hit, left-edge aligned to each cell, shown instantly (delayMs=0), viewport-aware flip.
• 🧩 Granularity-linked model table: exact in-window aggregation via session×day and model×day secondary maps (no approximations), with window totals row and empty state.
• ⚡ Sidebar hover badge: 1.25亿token today, silent 30s polling, rolls over at midnight automatically.
• 🚿 Zero-usage filtering: models that only produced requests but no real tokens are excluded from the breakdown and from request totals.
• 🌗 Theme-native: every color maps to DSH theme variables (--dsw-alias-*); light/dark just work.
• 🛠 usage_report model tool: ask your agent "how many tokens did I use today?" without opening the panel.

Install

Option A (recommended): one command, self-mounting

dsh plugin --profile web add dsh-plugin-token-usage

The package ships its own cordis.patch.yml bundle patch, so the host half (HTTP API + model tool) activates automatically.

Option B: manual mount

1. Put this directory into ~/.dsh/profiles/web/node_modules/ (or pnpm add file: it);

2. Append to ~/.dsh/profiles/web/cordis.patch.yml:

   - insert:
       - id: token-usage
         name: 'dsh-plugin-token-usage'
         config:
           ttlMs: 15000
   

3. Restart DeepSeek Harness.

⚠️ Pick one. If the bundle patch already mounts it, do NOT manually insert the same id — that would double-load the plugin.

Upgrading from the manual install? If you previously added the insert block above to your profile, delete it before restarting — with the self-mounting bundle patch present, the same id would be registered twice and startup crashes with duplicate loader entry id: token-usage.

Configuration

Usage

• Web GUI: click the bar-chart icon on the sidebar settings row → usage modal; Esc or click the backdrop to close.
• Chat tool: ask your agent to call usage_report (refresh forces a rescan, top caps model rows — default 10, max 50).

Privacy

Read-only parsing of local logs under ~/.dsh/sessions/** (streamed zstd decompression, 8-way concurrency). No network requests, no telemetry, no writes.

License

MIT