whale-girl: A Desktop Pet DSH plugin for DeepSeek Harness
vlln/whale-girl
A desktop pet plugin for DSH Web GUI, a floating companion with drag, feed, and play interactions.
Add a draggable, feedable QQ-pet-style companion to the DeepSeek Harness Web GUI, making coding sessions less lonely.
dsh plugin --profile web add github:vlln/whale-girl- Category
- Entertainment
- Platform
- DSH-Plugin
- Author
- vlln
- Distribution
- Plugin
whale-girl Key Features
whale-girl Repository
whale-girl Repo Summary
whale-girl is a desktop pet plugin (DSH plugin) for DeepSeek Harness, appearing as a QQ-pet-style companion floating at the bottom-right of the DSH Web GUI. It addresses the monotony and loneliness of long coding or session work by providing a draggable, feedable, and playable companion that accumulates experience levels, titles, and memories based on task completions and session activity. Core capabilities include a 15-state machine (idle, working, celebrate, error, sleep, etc.), configurable size, opacity, and walking toggle, and character switching.
What core features does the whale-girl DSH plugin support?
whale-girl offers a rich interactive state machine: dragging the pet causes a diagonal stretch (drag); clicking the menu allows feeding (eat) or playing (play), triggering joy (joy); idle for over 60 seconds leads to sleep (sleep), with wake (wake) on interaction; task completion or level-up triggers celebrate (celebrate); failure or errors cause error (error) then disappointment (disappointed); new sessions trigger welcome (welcome); during session thinking it shows think (think); waiting for approval shows wait (wait); periodic walking (walk); and normal idle (idle). Full state transition semantics are in docs/state-machine.md.
How to install the whale-girl DSH plugin?
whale-girl is an official bundle plugin format, managed via DSH profiles. The recommended method is git source installation (build artifacts are included), or local directory installation. After installation, restart the web to activate the bundle layer, and the pet appears at the bottom-right. Updates use the update command.
dsh plugin --profile web add github:vlln/whale-girl#main
# or local directory: dsh plugin --profile web add <whale-girl local path>
How to configure whale-girl?
Configuration is done via the whale-girl section in the host's settings.yaml or through the settings UI, with hot-reload without restart. Key parameters include enabled (web rendering toggle), size (pet size 64–160 px), opacity (normal opacity 0.2–1), walk.enabled (walking toggle), and sleepAfterMs (idle time before sleeping). Note that the semantic layer (XP/title thresholds) is not configurable to maintain ledger consistency.
What characters and state sprites does whale-girl support?
The menu "🎭 Switch Character" cycles through characters, each providing all 15 state sprites, with the sprite contract in docs/sprites-spec.md. Guidelines for contributing new characters are in docs/adding-a-character.md. The character design is by ZipZipPipe (from the "Whale Girl" sticker set), and sprites are generated based on that design.
What value does whale-girl provide as a reference implementation?
whale-girl is a complete template for the official repository-plugin format, not tied to a specific baseline version, evolving with the official mechanism. Its structure (lib/ separated from docs/decisions/scripts) and conventions (gates + decision records + full sprite contract) serve as a reference for developing new plugins. Maintained by vlln under the MIT license, last updated in 2026-08.