📊 dsh-usage-stats
API spend monitoring for DeepSeek Harness: per-request detail, previous-period comparisons, and chart-backed history in one panel.
See every token you pay for.
English · 简体中文 · Español · Português · हिन्दी
Compatibility
| Aspect | Status |
|---|
| Harness | DeepSeek Harness 0.1.0-rc.8 |
| Node | ^22.19.0 || >=24.0.0 |
| Surfaces | Host + web client (Settings → Usage tab); the /usage command |
What you get
dsh-usage-stats turns the session event stream into a complete spend-monitoring panel:
- Summary cards — today / this week / this month / all-time, each with a signed percentage delta against its previous period (yesterday / last week / last month).
- Per-request conversation detail — every priced request's start time, turn/step, model, input/output/cache-read/cache-write tokens, cost at the request-time price, and peak badge; durable through restarts via the session projection seam (bounded ring,
requestLog config).
- Day / week / month views — current-vs-previous comparison panels (cost, tokens, calls, peak calls + deltas) with the period's per-day lines.
- History panel — a dependency-free daily-cost bar chart (peak-tinted bars, hover details) plus a per-day table (cost / tokens / calls / peak, per-model drill-down), 90 days by default (~a year in the durable layer).
- Custom range — any from/to dates: range total, daily chart, per-week lines, per-model breakdown.
- Pricing — built-in USD table merged with
config.prices; peak-hour pricing anchored at request start (peak.hours windows × multiplier, or explicit peak.prices); calendar bucketing follows peak.timezone.
- Carbon & latency — token→carbon bridge (tokens × kWh/token × PUE × regional grid intensity) and per-model latency percentiles.
Quick start
# 1. Add the bundle to your profile (tarball channel)
pnpm pack
dsh plugin --profile web add ./dsh-usage-stats-<version>.tgz
# 2. Restart and verify the row
dsh web --restart
dsh --profile web --dump-config | grep -A2 'id: usage'
Then type /usage in a conversation and open the Settings → Usage tab.
Install & remove
- npm channel (published versions):
dsh plugin --profile web add dsh-usage-stats-alhabor — npm registry, released from tags.
- git channel (latest
main): dsh plugin --profile web add "github:PerryLink/dsh-budget#main" — the prepare script builds with production dependencies only.
- tarball channel: run
pnpm pack in this repo, then dsh plugin --profile web add ./dsh-usage-stats-<version>.tgz.
- remove:
dsh plugin --profile web remove dsh-usage-stats.
Configuration
Every key is a Schemastery-validated cordis field (defaults inline in cordis.patch.yml).
| Key | Default | Meaning |
|---|
prices | {} | Per-model per-1M-token prices, merged over the built-in USD table |
defaultPrice | {input: 1.0, output: 3.0} | Fallback for models absent from both tables |
peak.enabled / timezone / hours / weekendOffpeak / multiplier / prices | true / Asia/Shanghai / [[9,12],[14,18]] / true / {input:2, output:2, cacheRead:2, cacheWrite:2} / {} | Peak-hour pricing: requests starting inside a window (Mon–Fri only — weekends are all-day off-peak since DeepSeek's 2026-08-23 rule) price through peak.prices (or base × multiplier); day/month bucketing follows peak.timezone |
modelAliases | {} | Dated/legacy model ids → canonical pricing id |
currency | {code: CNY, rate: 1.0, decimals: 2} | Display currency (amount = computed × rate; for direct CNY pricing set rate: 1.0 and fill prices with CNY rates) |
outputLanguage | zh | /usage output language: en / zh |
historyDays | 90 | Days of per-day history kept in the panel snapshot (1..365; the durable layer keeps ~a year per session) |
requestLog.enabled / size | true / 200 | Per-request detail switch and per-session ring size (10..2000) |
carbon.enabled / region / pue / energyKwhPerToken | true / global / 1.58 / 0.000007 | Carbon bridge (regions: global, us, eu, china, india, uk, france, iceland) |
latency.enabled / windowSize | true / |
Surfaces
| Surface | Kind | Notes |
|---|
/usage | command | Overview (session/today/yesterday/this week/last week/this month/last month/all-time) |
/usage models | days | sessions | week <monday> | range <from> <to> | command | Model breakdown / daily history / session list / one week / custom range |
| Settings → Plugins → Usage | settings tab | Summary cards, conversation detail, day/week/month comparisons, custom range, history chart |
usage/status, usage/range | Typert Remote | Client channel (the tab consumes these two methods) |
Permissions & data
- Permissions:
session:append (command audit only), native-code:none; no outbound network.
- Data: everything shown is a read-only aggregate over official session events; the plugin never appends custom event types to the session log (the rc.8 read path refuses unknown types) — durable state lives entirely in session projections.
- Fail loud: invalid prices, timezones, ratios, regions, and bounds fail at mount time.
Known limits
- Per-request detail is bounded per session (latest 200 by default); older requests live on only in the aggregates.
- Previous-period deltas show "new"/"flat" when the durable history is shorter than one full period.
- Built-in prices drift; override entries with
config.prices.
Development
pnpm install # node ^22.19 || >=24
pnpm run typecheck # tsc: src + tests against the local harness checkout
pnpm run typecheck:ci # tsc against the published 0.1.0-rc.8 types (no paths)
pnpm test # vitest: 80 tests
pnpm run build # tsc declarations + tsdown bundles (lib/)
pnpm run verify:self-contained # dependency specs resolve from the registry
pnpm run verify:artifacts # built ESM face + typert manifest + client bundle
pnpm pack # the published tarball
Topics
dsh, dsh-plugin, deepseek-harness, deepseek, cordis, budget, cost-tracking, carbon-footprint, latency-benchmark, token-usage
Contributors
- @PerryLink — creator and maintainer: aggregation, budget governance, carbon and latency ports, the Settings tab, and the five-language docs.
PerryLink DSH Plugin Family
This project is one of the 29 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:
| Plugin | One-liner |
|---|
| dsh-auto-review | Second-model auto-review on the approval chain, fail-closed by default |
| dsh-background-agents | Durable background child agents with a Web UI sidebar, messaging and interrupt |
| dsh-budget | Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel. |
| dsh-checkpoint-rewind | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore |
| dsh-claude-move | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH |
| dsh-click | Cross-platform native desktop control for DeepSeek Harness — Windows first. |
| dsh-composer-history | Terminal-style input history for the web composer: arrows, Ctrl+R search |
| dsh-defend | Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness. |
| dsh-doublecheck | Engineering-discipline guard: requirements grill, test gates, adversary review |
| dsh-draw | Unified static-image generation routing for DeepSeek Harness. |
| dsh-fast | Read-only performance diagnostics for DeepSeek Harness. |
| dsh-github | GitHub PR/issues integration for DSH, every write gated by approval |
| dsh-library |
License
Apache License 2.0 © 2026 dsh-budget contributors
