dsh-key-usage: A Usage and Balance Panel in the DeepSeek Harness Sidebar

What Does It Do?

dsh-key-usage is a DSH plugin for DeepSeek Harness that adds a "Usage" entry to the sidebar and turns local ledgers and host session events into a full usage dashboard. It solves the problem of not knowing how many tokens you have spent, what they cost, or how much balance remains, letting you inspect usage by channel, project, and session directly inside the harness. Maintained by xyl886 under the MIT license and written in TypeScript, it is read-only and local-first, with only balance and quota queries reaching provider APIs.

Core Features

• Overview panel: lists each channel key with today's and last-30-day usage plus 30-day cost, alongside a yearly activity heatmap whose tooltips break down the day's models.
• Usage details: switch between today, week, month, total, and custom ranges, with call-count, token, and cost cards, channel share bars, and day-by-day (hourly for a single day) stacked charts that expand down to models.
• Project and session views: aggregates calls, tokens, share, cost, and last activity by working directory, and lists time, duration, tokens, hit rate, and cost per session, all searchable, filterable, and sortable.
• Balance and quota: queries each channel's official balance and subscription window in real time, falling back to a local snapshot with the source clearly labeled when a query fails.
• Privacy and safety: never reads credential files, writes no files, changes no host configuration, and exposes only read-only GET endpoints restricted to loopback requests.

How to Use This Plugin?

Once enabled in DSH, a "Usage" item appears in the left navigation; opening it shows the full-page panel with the overview key list and yearly heatmap by default. In the usage details tab, pick a range with the range switcher (today, week, month, total, or custom) and filter by channel to inspect the stacked charts and daily breakdown; the project and session tabs aggregate by working directory and by session, both searchable and sortable. The balance and quota tab is the only path that goes online: the server queries provider APIs, caches results for 60 seconds, and re-queries when you press refresh, labeling the reason whenever it falls back to a local snapshot. Client changes take effect on page refresh, while server-side plugin code loads at host startup, so exit and reopen the app after installing.

How to Troubleshoot This Plugin?

When a balance or quota card shows that it is displaying a local snapshot, the live query did not succeed, usually because that channel's API key cannot be resolved by the host credentials service or is missing from the process environment; restore the credential as described in the official docs and retry. If project, session, or hourly data reports as unavailable, the host session persistence service is typically missing or failed to read, and the remaining pages keep working, so no further action is needed.