Back to directory

dsh-usage-panel

In a curated listMaintenance: Active

alfredchaos/dsh-usage-panel

View read-only token usage, session activity, and provider/model breakdowns under Settings → Usage.

View on GitHub
$ dsh plugin --profile web add dsh-usage-panel

14

stars

2

forks

TypeScript

Language

MIT

License

2026-08-15

Created

2026-09-15

Last push

MIT-licensed dsh bundle plugin: read-only token accounting from session logs with fork de-duplication, UTC day buckets, a 10-minute freshness window and JSON / CSV export.

DSH integration

Native runtime

Author-claimed

Safety audit

Unaudited

Last verified

2026-11-10

License

MIT

01What can it help you accomplish?

  • See how many tokens a DeepSeek Harness deployment has actually burned, broken down by model, provider and day

    A Settings → Usage page with all-time totals, cache hit rate, a six-month activity heatmap, stacked daily bars, top sessions, provider bars, a model donut and JSON/CSV export

    DeepSeek Harness users and teams who want cost visibility without adding a proxy or modifying their session logs

  • Export usage numbers for billing, budgeting or a spreadsheet

    Full JSON, daily CSV and per-model CSV, guarded against formula injection, RFC 4180 compliant, UTF-8 BOM

    Anyone who has to reconcile token spend outside DSH

02How to install into DeepSeek Harness

Prerequisites

  • A `web` profile — the page lives under Settings → Usage
  • Developed against DeepSeek Harness `0.1.5-rc.1` (README implementation note)

Installation steps

  1. 01

    From npm (recommended): `dsh plugin --profile web add dsh-usage-panel`

    $ dsh plugin --profile web add dsh-usage-panel

  2. 02

    Or from GitHub: `dsh plugin --profile web add github:AlfredChaos/dsh-usage-panel`

    $ dsh plugin --profile web add github:AlfredChaos/dsh-usage-panel

  3. 03

    Or from a local checkout: `dsh plugin --profile web add ./dsh-usage-panel`

    $ dsh plugin --profile web add ./dsh-usage-panel

  4. 04

    Restart `dsh --profile web` and open Settings → Usage

    $ dsh --profile web

Verify the integration

  • The Usage page renders KPI cards and the heatmap straight from cache on first load
  • The refresh button forces a synchronous rescan

Rollback

  • `dsh plugin --profile web remove dsh-usage-panel`

03DSH integration and capability boundaries

DSH integrationNative runtime

Native dsh bundle plugin: `dsh plugin add` appends it to the profile’s bundle list and the bundle patch row activates the host half, which serves `/api/usage-stats/overview` on the shared `/api` transport and registers a client half for the Settings → Usage page.

  • Incremental session projection

    committed session events→four disjoint buckets (uncached input, output, cache read, cache write) plus per-model, per-provider and per-day (UTC) maps

    checkpoints are durable, so restarts and keep-warm passes cost almost no replaythe plugin never writes anything back to the session logs
  • Accounting rules

    `request/header`, `request/context`, `assistant/message`, `llm/retry`, `compaction/summary` events→model attribution from context base / header override, step usage replacing streamed provisional usage, retries counted as retries not tokens, compaction attributed to its own model

    reasoning tokens are already inside output and are never added again
  • Fork de-duplication

    events inside the durable seed prefix (`inheritedEventCount`)→forked sessions are not double-billed for their parents’ usage

    `session/end-seed` markers only delimit resume/fork accounting epochs
  • Cached payloads with staleness flag

    a payload request from the browser→a payload considered fresh for 10 minutes; older ones returned immediately with a `stale` flag while a rescan refreshes the cache

    a keep-warm timer rescans every 10 minutesthe browser also keeps the last successful payload in localStorage, versioned and structure-validated

04Who is it for? When not to use it?

Good for

  • DeepSeek Harness users and teams who want cost visibility without adding a proxy or modifying their session logs
  • Anyone who has to reconcile token spend outside DSH

Not for

  • The README says the plugin was developed against DeepSeek Harness `0.1.5-rc.1`; there is no declared compatibility matrix in the README.

05Compatibility, maintenance and safety notes

  • The README says the plugin was developed against DeepSeek Harness `0.1.5-rc.1`; there is no declared compatibility matrix in the README.
  • Day buckets and exports use UTC calendar days (`YYYY-MM-DD`), and the heatmap subtitle declares the scope (“last 6 months · UTC”).
  • When the projection services are unavailable the plugin falls back to replaying every session log through the read-only `sessionQuery` service, which is slower than the incremental path.
  • Statistics cover persisted session logs only; the README does not claim billing-grade accuracy or reconciliation with a provider invoice.
2026-08-152026-09-15v0.2.3

MIT · actively maintained (latest release v0.2.3, 2026-09-15)

06Frequently asked questions

Does the plugin modify my session logs?

No. It aggregates persisted session logs through a session projection (or a full rescan fallback) and never writes anything back, so statistics survive restarts and cover sessions from before the plugin was installed.

How is cache hit rate calculated?

`cache read ÷ (uncached input + cache read + cache write)`, with the read and write magnitudes shown alongside it.

Will forked sessions be double-counted?

No. Events inside the durable seed prefix (`inheritedEventCount`) are never counted, so a forked session does not double-bill its parent’s usage; `session/end-seed` markers only delimit resume/fork accounting epochs.

Why do the numbers sometimes show as stale?

A payload is fresh for 10 minutes; older ones are returned immediately with a `stale` flag while a rescan refreshes the cache. A keep-warm timer rescans every 10 minutes, and the refresh button always forces a synchronous scan.

Which timezone are the daily buckets in?

UTC calendar days (`YYYY-MM-DD`) for both buckets and exports; the heatmap subtitle declares the scope as “last 6 months · UTC”.

08Data and sources

  • Author-claimedgithub.comf77e7f4a6f15…

    The plugin aggregates persisted session logs (incrementally, via the session-projection mechanism) and never writes anyt…

  • Author-claimedgithub.comf77e7f4a6f15…

    The plugin ships as a bundle: `dsh plugin add` appends it to the profile's bundle list

This page is generated from the project’s public documentation, repository metadata and a structured parse of DSH Plugins; last verified on 2026-11-10. Found an error? Submit a correction.

🏆

Best DeepSeek Harness Plugins

Twelve plugins worth installing first — picked from the whole catalog, across every category.

DSH Plugins is an independent community directory of DeepSeek Harness plugins. Not affiliated with or endorsed by DeepSeek. Third-party plugins are not security-audited — review the source before installing.

New DeepSeek Harness plugins, weekly. No spam.