deepseek-whale-pet

A transparent, always-on-top desktop pet for Windows — a cute whale companion that lives on your desktop, walks around, talks, and keeps an eye on your DeepSeek Harness (DSH) sessions. When a DSH work turn finishes, it pops a speech bubble and announces it in a cute voice; when DSH is waiting for your approval or a question, it nudges you to act. It can also look up your DeepSeek API balance and launch DSH for you.

The pet reads DSH's session data in a read-only way and never modifies or restarts DSH.

Features

Desktop pet

• Three-view walking: side (auto-mirrored), back (walking up), front (walking down).
• Three movement modes: Free roam / Follow cursor / Stay put.
• Interactions: drag (with voice lines), single-click bounce + sass + chat entry, double-click feeding (dried fish, cake, lollipop, dumplings, diamond).
• Speech-bubble system: random lines, reaction lines, and an inner "chain-of-thought" voice shown in a gray italic bubble.
• Detail animations: breathing, swaying, jumping, eating, direction cross-fade, acceleration/deceleration inertia, and random resting.
• AI chat: click the 💬 entry to chat via the DeepSeek deepseek-chat model, keeping up to 40 messages of context.
• Weather lookup (right-click menu, data from wttr.in).
• System monitoring: bubbles when CPU > 90%, RAM > 95%, or NVIDIA GPU > 80 °C.
• Tray icon, always-on-top, click-through (mouse passthrough), start-on-boot, and remembered position/settings.

DSH integration

• DSH session-done notification: when one DSH work turn finishes, the pet shows a bubble and speaks it aloud.
• DSH waiting-for-user notification: when DSH is waiting for an approval or a question, the pet prompts you to act.
• DeepSeek balance lookup: "View DeepSeek Balance" in the right-click menu, with a bubble + voice readout, plus an automatic low-balance alert (silent hourly patrol).
• Auto-launch DSH: a few seconds after startup, the pet probes 127.0.0.1:<dsh_port> and, if DSH Web is not running, launches it. It only starts DSH — it never stops or restarts it.

Requirements

• Windows 10 or 11
• Python 3.11+ (tested with 3.13)
• DSH (DeepSeek Harness) — optional, required only for the DSH integration features
• An internet connection for the DeepSeek API, edge-tts voices, and weather

Installation

Option A — one-command installer

Double-click install.bat. It:

1. installs Python dependencies (pip install -r requirements.txt),
2. enables start-on-boot (which also enables the auto-launch-DSH behavior),
3. starts the pet.

Option B — manual

py -3 -m pip install -r requirements.txt
py -3 desktop_pet.py

For daily use, just double-click start_pet.bat.

Start on boot can also be toggled from the right-click menu ("Start on Boot"). To remove it from a command line, run: py -3 desktop_pet.py --uninstall-autostart (or double-click uninstall.bat).

Configuration

The default configuration template is config.example.json. On first run the pet creates the actual config.json next to the script (in source mode) or under %APPDATA%\WhalePet\config.json (in a frozen .exe build).

Privacy & Security

This is a pure client-side desktop app: it opens no listening ports and has no inbound attack surface. Outbound data is limited to the following, all sent over HTTPS:

API key storage: your API key is stored in plaintext in config.json (readable only by your own Windows account by default). To avoid this, leave ds_api_key empty and keep the key in the DSH credentials file instead; more advanced setups can use the Windows Credential Manager (DPAPI).

DSH access: the pet only reads DSH's local session data. It never modifies, stops, or restarts DSH.

Usage

Starting

• start_pet.bat — start the pet normally.
• install.bat — install dependencies + enable start-on-boot + first start.
• py -3 desktop_pet.py — start directly from a terminal.

Interactions

Menu highlights

• View DeepSeek Balance — bubble + voice readout of your remaining balance.
• DSH Status — list the working state of recent DSH sessions.
• Open DSH Web — open the DSH Web UI at http://127.0.0.1:<dsh_port>.
• Voice Announcements / Voice Mode / Voice Preset — control voice output.
• Auto-launch DSH — toggle auto-launching DSH on startup.

Voice announcements

The pet can speak through two engines:

• edge — Microsoft Edge online TTS (free, no key). Results are cached under %APPDATA%\WhalePet\voice_cache\.
• sapi — the built-in Windows offline voice, used automatically as a fallback when edge-tts is unreachable.

In Notification only voice mode, the pet stays quiet during normal use and only speaks for task events (done / waiting / balance alerts).

DSH integration

The pet polls DSH's session data every 2 seconds (read-only):

• ~/.dsh/storages/session_projcache.json — session titles.
• ~/.dsh/sessions/<workspace>/<session-id>/session.jsonl.zstd — the event log, used to detect exactly when a turn finishes (turn/end) and when the model is waiting for you (an ask_user_question call or a pending approval).

Set DSH_HOME to override the ~/.dsh location. dsh_dir (or auto-detection) tells the pet where DSH is installed so it can launch DSH Web if it is not already running.

Developer tools

The tools/ directory contains helper scripts used during development to audition voices, rework sprites, and package a release. They are not required to run the pet — ordinary users can ignore them.

The ChatTTS scripts need torch, torchaudio, and 2noise/ChatTTS installed (via pip or per its repository instructions); they are heavy and optional.

Voice samples

The samples/ directory holds audition recordings of candidate voices: edge-tts variants (Xiaoyi / Xiaoxiao and friends) and ChatTTS multi-seed auditions. The pet's default voice is built in, so it runs fine without samples/. To regenerate the candidates, run the corresponding tools/ script — the edge-tts scripts need nothing extra, while the ChatTTS scripts require installing torch and ChatTTS first.

Running the tests

py tests/test_watch.py

The test requires zstandard (pip install zstandard). It drives the DSH event-state machine with fake (zstd-compressed) session logs and verifies that ordinary tool activity is not misreported as "waiting", that only questions and approvals report "waiting", and that only turn end reports "done".

FAQ / Troubleshooting

1. The pet does not speak.

• Make sure voice_enabled is true in config.json (or check the "Voice Announcements" menu item).
• The edge engine needs internet access; if it is offline, it falls back to the Windows SAPI voice. Check that Windows has a voice installed (Settings → Time & Language → Speech). You can force offline voice via the menu: Voice Preset → "System offline voice (no network)".

2. DSH integration shows no notifications.

• Confirm DSH is installed and running (or that dsh_dir points to it, and dsh_launch is enabled).
• The pet reads ~/.dsh; if your DSH home is elsewhere, set the DSH_HOME environment variable to that location before starting the pet.
• A session must be recent (written within the last 24 hours) to be tracked.

3. How do I remove start-on-boot?

• Right-click the pet or tray icon → untick "Start on Boot", or
• double-click uninstall.bat, or
• run py -3 desktop_pet.py --uninstall-autostart.

4. The balance query fails.

• Set ds_api_key in config.json (or set DEEPSEEK_API_KEY in ~/.dsh/.credentials.yaml). The key must be a valid DeepSeek Open Platform key. The balance endpoint needs a working internet connection.

License

Released under the MIT License.

Credits & References

This project builds on the work of the following projects:

• dafeiyu-pet — the pet behavior, sprites, and base application derive from 1190fasheqi/dafeiyu-pet (MIT License). See NOTICE for details.
• edge-tts — online voice synthesis via rany2/edge-tts.
• ChatTTS — the audition scripts use 2noise/ChatTTS.
• wttr.in — weather data from wttr.in.
• DeepSeek Harness — the DSH session state this pet watches is produced by deepseek-ai/deepseek-harness.