A desktop pet plugin for the DeepSeek Harness (DSH) Web UI. A small whale floats in the bottom-right corner and reacts to your agent’s state in real time.
It uses the official DeepSeek whale outline, pure DOM animations, zero runtime third-party dependencies, and WebAudio-synthesized sound effects (no audio files).
Open the standalone preview page to try every state and interaction:
👉 https://nzl153.github.io/dsh-pet-whale/preview.html
The repository’s preview.html is the same page and can be opened locally.
| Capability | Description |
|---|---|
| State machine | idle / think (diving) / working (swimming + typing + code particles) / celebrate (leaping + bubbles) / error (shaking + black lines) / disappointed (a brief slump after an error) / wait (waiting for your input); priority: error > celebrate > think > working > idle |
| Turn semantics | Never idle while a turn is running: with tools = working, without tools (text or internal reasoning) = think diving; keyboard animation sticks for 2.5s during tool-heavy phases |
| Interactions | Click to poke, double-click 360° flip, drag with >_< eyes, right-click quick menu, mouse-follow eyes, 20s idle sleep |
| Quick menu & settings | Right-click opens a compact 5-item quick menu; “More settings” opens a grouped panel (appearance / behavior / rest) that scales as features grow |
| Pretend work | “Pretend to work” mode keeps the typing animation on; preference is persisted |
| Think ticker | While thinking, the latest reasoning text scrolls above the whale (can be toggled) |
| Smart avoidance | In idle, the whale moves aside when the cursor lingers nearby; grabbing/right-click cancels and cools down for 8s |
| Theme sync | Follows DSH light/dark theme for bubbles, dialogs, and shadows |
| Background power saving | Animations, sounds, and the think ticker pause when the page is hidden |
| Idle micro-movements | Random swimming, looking around, and bubble blowing |
| Error care | Click the whale during error state to copy the error text |
| Skins | 7 built-in palettes (default Theme Blue), extensible by adding one line in src/client/palettes.ts |
| Hide/recall | Hide to a small 🐳 button; state persists across refresh |
| Scheduled hide | Hide after 1 hour or every day at 22:00 |
| Free swimming | Toggle “Swim” to let the whale roam the page along cubic Bezier paths, with banking, adaptive flipping, depth dives, wake ripples, and splashes; it yields while the agent is busy, and the preference is persisted |
| Localization | Full Chinese and English copy, following the DSH locale service automatically; the standalone preview page detects the browser language and can be overridden manually |
| Stats | The settings panel keeps running counts of completions, interactions, errors, and days spent together |
| Sound | WebAudio-synthesized sounds, can be muted |
| Accessibility | Respects prefers-reduced-motion |
Requires DSH >=0.1.0-rc.6 (web profile).
# Local directory install (the repo already contains built lib/, no build needed)
dsh plugin --profile web add link:/path/to/pet-whale
# Or install directly from Git
dsh plugin --profile web add "github:nzl153/pet-whale#main"
After installation, restart dsh web (the host half is composed at startup). Client-side changes only need a hard refresh (Ctrl+F5).
pnpm install
pnpm typecheck # TypeScript type check
pnpm build # tsdown → lib/index.mjs + lib/client.js
pnpm test # jsdom smoke test (state machine / interactions / skins / cleanup)
src/client/palettes.ts — palette extension point. Add one line for a new skin.scripts/extract-whale.mjs — sync the V2 SVG from preview.html into src/client/whale.ts.scripts/verify-live.mjs — one-click live verification after restart.ctx.sessions session snapshots (running / runningCalls / partial / lastAgentError / turnEnds).