dsh-token-balance

A tiny token-usage & account-balance monitor for DeepSeek Harness (DSH), rendered right inside the web UI.

tokbal shows you live LLM token consumption and your DeepSeek account balance without leaving the conversation:

• A sidebar badge — compact ⚡ 1.2k · ¥23.45; click it to force a balance refresh.
• A stats row above the input box — per-session ↑input ↓output 💾cache 🧠reasoning tokens, cumulative totals, and the current balance, refreshed every 3 seconds.
• Works across all sessions: counting is process-wide, with a per-session breakdown kept separately.

How it works

Two halves, both tiny:

Half	File	What it does
Host	lib/index.js	Subscribes to llm/stream events and accumulates usage chunks (input / output / cache-read / reasoning tokens) per session and globally; queries the official DeepSeek balance endpoint from the host process; exposes two same-origin JSON routes.
Client	lib/client.js	A handwritten browser bundle served as-is by client-modules; polls /tokbal/state and renders the badge + stats row into sidebar/composer slots.

The API key never leaves the host process, and the only outbound call is to your configured DeepSeek API base URL.

Requirements

• DeepSeek Harness desktop (web UI)
• An API key resolvable through DSH credentials — default ref DEEPSEEK_API_KEY (override via settings llm-deepseek.apiKeyEnv)
• Balance is queried from the configured base URL — default https://api.deepseek.com (override via settings llm-deepseek.baseURL)

Installation

Option A — install script (recommended)

# from the repo root
.\scripts\install.ps1

The script copies the plugin into your profile's local plugins and registers it in %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml (skipped if already registered).

Option B — manual

1. Copy this package into the profile's local plugins:

   Copy-Item -Recurse . "$env:USERPROFILE\.dsh\profiles\node_modules\@local\tokbal"
   

2. Register it in %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml:

   - insert:
       - id: tokbal
         name: '@local/tokbal'
   

3. Reload the web UI (hard refresh). That's it — no build step.

Optional: sidebar "settings zone" placement

Out of the box the badge renders in the sidebar footer actions area (works on a stock shell).

To move it right above the settings gear (the footer's settings zone), apply the tiny shell patch:

.\scripts\patch-sidebar.ps1 -AppRoot "C:\Path\To\DeepSeek Harness"

The plugin auto-detects the environment:

• With the patch → badge renders in sidebar.footer.settings, directly above the gear.
• Without the patch → falls back to sidebar.footer.action, so it still shows on stock builds.

Note: the patch edits the vendored dsh-client-ui-sidebar bundle inside the app's resources/host/node_modules and adds a new list slot next to the settings area. It is overwritten when the app updates — re-run the script after an update. See patches/ for details.

Usage

• Badge — ⚡ 1.2k · ¥23.45. Hover for a full tooltip (this run's totals + balance + click hint); click to refresh the balance immediately.
• Stats row (above the input box) — per-session ↑input ↓output 💾cache 🧠reasoning · cumulative total · balance, polling every 3 s.
• Balance freshness — auto-refreshes when stale: ≥ 45 s when the UI is watching, plus a 60 s host-side fallback poll.

HTTP endpoints (same-origin, no CORS, no key exposure)

Method	Path	Description
GET	/tokbal/state	Snapshot: global totals, per-session breakdown, balance
POST	/tokbal/refresh	Force a balance refresh, returns the snapshot

Project layout

lib/index.js          Host half — usage counting, balance, JSON routes
lib/client.js         Client half — handwritten browser bundle (no build step)
scripts/install.ps1        Copy into profile + register in cordis.patch.yml
scripts/patch-sidebar.ps1  Apply the optional sidebar settings-zone patch
patches/                   The sidebar patch (diff + notes)

Development

• The client bundle is intentionally handwritten and served verbatim by client-modules — edit lib/client.js, refresh the page.
• The host half is plain ESM (type: module) loaded by the host runtime.
• Counter scope is "since plugin start": totals reset when the host restarts.

License

MIT © dsh-token-balance contributors