What Is whale-girl? A QQ-Pet-Style Desktop Companion for DSH

whale-girl is a desktop pet plugin for the DeepSeek Harness (DSH) Web GUI: a QQ-pet-style little whale floating at the bottom-right of the interface that accrues levels, titles, and memories from completed tasks, session time, and companionship — and can be dragged, fed, and played with. Based on the official README, this article covers what whale-girl is, its core features, installation, typical usage, and common troubleshooting.

What Is whale-girl?

whale-girl addresses "long DSH sessions lack playful feedback": it turns completed tasks and accumulated companionship into visible levels, titles, and memories, making the tool feel like raising a little pet. The facts below come from the official README (source):

whale-girl (GitHub repo vlln/whale-girl) is maintained by vlln, written in JavaScript, MIT-licensed, and ships as a bundle (dsh.bundle for plugin logic, dsh.client for browser rendering) in the DSH Plugin ecosystem. Like the classic QQ pet, it floats at the bottom-right of the Web GUI and reacts to your usage rhythm: it celebrates when tasks complete, startles on errors, and naps when idle too long. Unlike a plain decoration, it bakes the "pet-raising" feeling into data — completed tasks, session time, and companionship accrue into levels and titles, and settle into memories (source).

What Are the Core Features of whale-girl?

whale-girl's core abilities revolve around "floating companionship + accruing growth + state-machine animation": a draggable, feedable, playable little whale that turns your DSH time into visible feedback. Feature facts come from the official README (source):

• Floating desktop pet: floats bottom-right of the Web GUI in QQ-pet style, appears automatically with the DSH web interface, and can be dragged anywhere.
• Drag, feed, and play: dragging triggers drag, feeding triggers eat, playing triggers play, with squishy press interactions — the pet reacts live to your actions.
• Levels, titles, and memories: completed tasks, session time, and companionship convert into experience; level-ups grant titles, and companionship details settle into memories, so even long usage cycles feel like growth.
• 15 state-machine-driven animation states: idle, working, celebrate, error, disappointed, joy, eat, play, drag, walk, sleep, wake, welcome, think, wait — task done or level-up triggers celebrate; task failed goes error then disappointed; idle beyond sleepAfterMs triggers sleep.
• Optional desktop companion app: a standalone app (whale-girl-desktop) keeps the pet resident on your OS desktop, collaborating with the web version through public endpoints.

How to Install and Enable whale-girl?

whale-girl installs as a bundle via the standard DSH Plugin command; restart the web client afterward and the little whale appears bottom-right. Installation matches any other DSH plugin, per the official README (source):

1. Confirm your environment and target profile. whale-girl is a DSH UI plugin; install it into the profile that runs the Web GUI. The examples use web as the profile name — swap in your own.

2. Run the official install command. From a DSH environment:

dsh plugin --profile web add whale-girl

Or from the GitHub source:

dsh plugin --profile web add github:vlln/whale-girl

Or pin the npm version (currently 0.1.0):

dsh plugin --profile web add whale-girl@0.1.0

3. Restart the web client. After installing, restart Web so the bundle (dsh.bundle + dsh.client) loads. A whale floating bottom-right means success.

4. Verify and manage the plugin. Confirm whale-girl is listed:

dsh plugin list

To update, re-run add for an overwrite install; to remove, use remove:

dsh plugin remove whale-girl

All add/update/remove operations go through standard DSH Plugin commands — no manual config editing.

Typical whale-girl Usage

Once installed, daily use is "play with it + watch it grow": dragging, feeding, and playing give instant feedback, and config edits apply live. The following usage is based on the official README (source):

1. Adjust pet size and toggle. Edit the whale-girl: section of the DSH settings file (settings.yaml), e.g.:

whale-girl:
  enabled: true
  size: 120

size is in pixels, range 64–160, default 110; enabled controls whether the web pet shows. Changes apply live, no restart needed.

2. Drag, feed, and play. Drag the little whale anywhere with your mouse (drag animation); "feed" (eat) or "play" (play) it from the settings or companion panel; press for a squishy response. Every interaction switches a state animation.

3. Watch event-driven feedback. Task done, level-up, or round end triggers celebrate; task failed or request error goes error then disappointed; idle beyond sleepAfterMs (default 60000ms) triggers sleep. Over time, experience accrues into levels and titles, and companionship details settle into memories.

4. Enable the desktop companion. To keep the pet on your OS desktop, install the standalone app globally:

npm install -g whale-girl-desktop

Requires Node ≥18; the rendering shell needs Rust (cargo). You can run --headless, or build the Tauri shell from source (first build ~5–15 min, artifact ~12MB). While it runs, the web pet hides; it returns within ~45s after exit or crash (presence contract).

whale-girl Troubleshooting

whale-girl issues usually fall into "pet not showing", "size and config", and "desktop companion" — most are solved with the steps below. Troubleshooting notes come from the official README and FAQ (source):

1. Symptom: pet not showing after install. Fix: restart the web client first so the bundle takes effect; then confirm enabled is true in the whale-girl settings (false usually means a desktop companion is running); finally, make sure you're not on an onboarding page, which hides the pet.

2. Symptom: size changes don't apply or look wrong. Fix: size only accepts 64–160; values outside may be ignored or cause issues. Confirm you edited the whale-girl: section of settings.yaml. Config hot-reloads, but plugin install/update still requires a web restart.

3. Symptom: desktop companion won't start or the web pet disappears. Fix: confirm Node ≥18, and Rust (cargo) if a rendering shell is needed; to keep only the web pet, set enabled to true and close the desktop companion. The companion is a standalone app, not installed via dsh plugin — don't look for it in the plugin list.

Use Cases and Notes

whale-girl suits users who want a bit of fun and companionship in long DSH workflows, but it is essentially a UI decoration plugin and carries no core business logic. Notes from the official README (source):

• Good for: users who spend long hours writing prompts, running tasks, or tuning agents in the DSH Web GUI; fans of desktop pets who want positive feedback; teams or individuals who want level/title-based motivation.
• Not for: minimal environments that tolerate no UI decoration; deployments with hard memory/performance constraints (the desktop companion needs Node ≥18, optionally a Rust shell).
• Note: the web pet hides while the desktop companion runs and returns ~45s after exit; XP and title thresholds are not configurable; "Switch Character" is greyed out when the manifest has a single character; the companion is a standalone app, unrelated to the dsh plugin channel.

Project Links

whale-girl is an MIT-licensed open-source project maintained by vlln. Plugin page: whale-girl plugin details.

This page is an independent guide rewritten from the plugin's official README — for authoritative documentation and the latest changes, refer to the source: vlln/whale-girl. Plugins are third-party code that runs on your machine after installation; listing here is not an endorsement — review the source before installing.