🐳 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

Absorbed source	Capabilities	Original author / repo
dsh-whale-widget	Bottom-right DeepSeek balance whale widget (balance, peak/off-peak pricing, random quotes & sounds, ledger / token usage modes)	zhu1090093659/dsh-web-ui
dsh-usage-stats	Per-DSH-session app usage data engine (token trends, model breakdown, activity)	lanlandeli/dsh-usage-stats

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

## ⚙️ Configuration

```yaml
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