A self-contained DeepSeek Harness (DSH) plugin: balances, today's usage & app-usage in one bridge

🐳 dsh-whale-usage

Self-contained DSH plugin that merges two existing plugins into one, and adds an
accounting / real-time-token / app-usage configuration panel on the desktop whale widget.

Does not modify the original packages — it absorbs their source logic at the bottom layer, so it is immune to upstream updates. After installing, you can maintain two fewer plugins (dsh-whale-widget and dsh-usage-stats may be uninstalled).

✨ What it is

dsh-whale-usage is the bridge & merge product: it replaces both plugins above with a single
self-contained one. © credits: CREDITS.md.

💡 Features

• Whale widget — kept as-is: balance, today's usage, peak/off-peak pricing, sounds, draggable.
• Usage settings panel — click the whale button at the bottom of the sidebar to open the "Little Whale · Usage" overlay and configure:
  • Accounting (ledger): accumulate today's usage from the balance delta (auto-resets daily and appends to the history ledger).
  • Real-time tokens: compute today's usage from DeepSeek platform tokens in real time.
  • App usage: show local DSH session usage (today / last 7 days Tokens, sessions, messages, most-used model).

🖼️ Screenshots

Usage config panel — usage mode / pricing / sounds / volume / peak times.

App-usage dashboard — tokens, sessions, messages, activity heatmap, top model.

Peak / off-peak pricing time periods (weekly).

🚀 Install

Install as a normal package — do NOT link it via a junction. A junction makes dependencies fail to resolve upward (e.g. schemastery / react) and desyncs the package name from cordis.patch.yml; both break DSH startup.

# Recommended — install from npm (published): https://www.npmjs.com/package/dsh-whale-usage
dsh plugin --profile web add dsh-whale-usage
# or: npm install dsh-whale-usage

# From source: this repo (or after cloning it on the target machine)
dsh plugin --profile web add <absolute path to this folder>

# Or install the built tarball
dsh plugin --profile web add <path>/dsh-whale-usage-0.1.4.tgz

# Or use the convenience scripts
bash scripts/install.sh                              # macOS / Linux / Git Bash
powershell -ExecutionPolicy Bypass -File scripts/install.ps1   # Windows

After installing, restart DSH and hard-refresh the browser (Cmd/Ctrl+Shift+R):

• the whale widget appears in the bottom-right corner;
• a "Little Whale · Usage" button appears at the bottom of the sidebar.

Because this plugin replaces the original two, uninstall dsh-whale-widget and dsh-usage-stats only after confirming this plugin works:
dsh plugin --profile web remove dsh-whale-widget · dsh plugin --profile web remove dsh-usage-stats

⚙️ Configuration

config:
  indexConcurrency: 2      # usage engine concurrency for reading historical sessions
  cacheWriteDelayMs: 1000  # debounce before writing local stats
  apiPath: /usage-stats/v1 # app-usage API prefix

Data is stored locally:

• Whale accounting / config: ~/.dsh/.dshw-*.json
• App-usage index: $DSH_HOME/usage-stats

🗂️ Repository structure

dsh-whale-usage/
├── lib/                # built plugin (host: index.js, usage-host.js, whale-host.js; client: client.js)
├── assets/             # whale images / sounds
├── cordis.patch.yml    # DSH bundle patch (plugin id dsh-whale-usage)
├── dsh.plugin.json     # DSH plugin manifest (id / version / main / client.main)
├── package.json        # npm package (name dsh-whale-usage, MIT)
├── LICENSE / CREDITS.md# MIT + upstream credits
├── README.md / README.zh.md
├── docs/               # dev notes (development.md) + screenshots
└── scripts/install.*   # one-click install scripts

🛠️ Development

See docs/development.md for architecture, building the tarball
(npm pack), and re-syncing upstream fixes (lib/whale-host.js, lib/usage-host.js).

📄 License & Credits

• License: MIT. The merged third-party source remains © its original authors — see CREDITS.md.
• This plugin is self-contained: it does not follow upstream automatically; re-sync fixes via docs/development.md.

中文说明见 README.zh.md。