whale-purse: A Whale Desktop Pet for DeepSeek Harness That Watches Balance and Session Spend

What Does It Do?

whale-purse is a DSH plugin for DeepSeek Harness that turns your DeepSeek balance and current session token usage and estimated cost into a draggable anime whale desktop pet floating over the DSH Web GUI. It solves the problem of not knowing how much a running task is spending or how much balance is left, so you no longer have to switch to a console or billing page to check. Clicking her opens a two-tab panel with live spend and history, with the balance refreshing every 30 seconds and cost every 3 seconds. It is maintained by Suiwan under the MIT license and was last updated on 2026-08-30.

Core Features

• Balance monitoring: polls the official DeepSeek balance endpoint every 30 seconds with concurrent request deduplication, keeping the last snapshot and flagging it as stale when a request fails.
• Session usage and cost estimation: reads the session tokenUsage projection and prices input misses, cache hits, and output as separate buckets, drawing the bar chart by cost share so cache-heavy tokens do not mislead you into thinking a session is expensive.
• Peak and off-peak pricing: automatically switches to peak rates during Beijing 9:00-12:00 and 14:00-18:00, shows the current tier and a countdown to the next switch, and re-fetches the official pricing page every 6 hours.
• Alerts and status reactions: warns in the panel and shows a red dot when balance drops below your threshold or today's spend exceeds budget, sends a browser notification when permission is granted, and bounces with a bubble when a background session finishes so you can jump straight to it.
• History trends: the history tab shows a 7-day spend bar chart plus a per-question cost breakdown for the current session, merging multi-step loops into a single row.
• Panel settings and theme adaptation: a gear icon lets you change the pricing model, low-balance threshold, and daily budget saved to a local JSON file, while colors follow the DSH light and dark themes and the pet is clamped back into view when you switch displays.

How to Use This Plugin?

Once enabled in the DSH web environment, the whale appears as a transparent sprite floating over the page; drag her anywhere and the position is stored locally so it survives refreshes and restarts. Click her to open the two-tab panel: the current tab shows balance and live spend, while the history tab shows the 7-day trend and a per-question cost breakdown for the session. To change behavior, click the gear in the panel's top-right corner and adjust the pricing model (auto detects flash or pro from the session request headers and skips estimation for non-DeepSeek models), the low-balance threshold, and the daily budget; changes take effect immediately without a restart. Balance queries rely on a DeepSeek API key in the environment, configured as described in the README, and if you also run DSH-better-sidebar the pet stays visible even when dragged over its Explorer panel.

How to Troubleshoot This Plugin?

When a balance or pricing request times out, the panel shows a friendly timeout message instead of an English aborted error, so check your network and credential configuration as described in the official instructions. If the balance reading is marked as stale, the most recent poll failed and the interface is showing the previous snapshot, which refreshes automatically once connectivity returns. If the panel reports that cost is not estimated, the session was detected as a non-DeepSeek model, which is expected behavior; you can set the pricing model manually in the settings panel.