Preface¶

Running tasks for extended periods and monitoring logs in DeepSeek Harness (DSH) often leaves the interface with only task flows and tool statuses, lacking a bit of “someone nearby” feedback. A common practice is to open a second window for videos or static wallpapers, but this doesn’t interact with the current task and can easily distract attention.

dsh-whale-musume (known in the community as “Whale Musume”) is a desktop mascot plugin designed for DSH: it hovers in a corner of the page, performs idle animations, switches to a “working on laptop” posture when it detects tool activity, and even allows for head pats, nurturing, and mini-games. All resources and states are local by default; the README specifies no telemetry or external requests; the weather feature is optional and only connects to the internet if a city is specified. Below, we introduce what it is, what it can do, and how to choose between the two official installation methods.

What Is It¶

dsh-whale-musume is released by maintainer Sutera-Diffusus, currently at version 1.4.1, under the MIT license, and compatible with DSH 0.1.0-rc.6 or similar versions. It is categorized under “Fun Costume Changes” in the SkillHub community directory and has approximately 32 stars on GitHub.

In one sentence: a pure frontend-injected DSH desktop pet plugin—it doesn’t modify DSH’s business DOM, but instead injects styles, scripts, and 90+ illustrations into the web interface via a script or bundle, providing companionship while coding in the bottom-right corner (or any position you drag it to).

Core Features¶

Mascot and Work State Interaction¶

By default, it hovers in a 200px form and supports dragging; while dragging, it switches to a “being picked up” illustration, with its body swaying in the direction of the cursor. During idle time, it randomly performs small actions like drinking coffee or stretching; transitions between idle and working states use a “press down → swap image → bounce up” sequence to avoid ghosting or flashing black.

When the page detects a tool running (data-running / data-state="ongoing"), the whale musume automatically switches to the laptop-holding posture, with a light blue glow and a “Working” label. Clicking in working mode may randomly trigger reactions like blushing or “stealing memory sticks,” without interrupting the working posture or randomly triggering small scenes.

Illustrations, Dialogue, and Interaction¶

Illustrations cover idle, working, thinking, and away states, as well as interactive zones for head pats, belly pokes, and tail pokes; there are also growth, game four-state, weather three-state, and holiday costume (Christmas / Halloween / Mid-Autumn / Spring Festival / Valentine’s Day) illustrations, plus 13 meme keyword-triggered emoji transformations.

The dialogue library contains 530+ lines, engaging in task-relevant idle chat every 5–8 minutes locally; it doesn’t interrupt during working states. Time-based greetings cover daytime hours, and it doesn’t disturb between 23:00–5:59 late at night. Mood and bond levels (Lv3 / Lv5 / Lv7) unlock different dialogues.

Single-clicking the head triggers blushing and particles; triple-clicking triggers starry-eyed celebration; the right-click menu offers feeding, poking, praising, mini-games, returning to original position, and opening settings.

Mini-games and Nurturing¶

Mini-game “Pop Bubbles · Bubble Party”: a 4×4 grid with normal, star, and bomb bubbles, 30 seconds per round; supports mouse and arrow keys + Enter / Esc. Daily play is limited to 3 rounds for nurturing rewards; excess rounds only count for score.

Nurturing dimensions include mood, favor, satiety, level, consecutive sign-ins, and time spent together. Daily 3 task slots, weekly sign-in board, 39 achievements, and an achievement wall in the settings panel. Bond Lv3 unlocks new idle animations, Lv5 unlocks the title “Whale Tide Guardian,” and Lv7 unlocks hidden easter eggs.

Weather and Settings¶

Path: DSH Settings → Mascot. Groups include companion behavior, weather, daily and nurturing, achievement wall, and data and reset. Capsule switches can independently disable the mascot, dialogue bubbles, particles, mini-games, keyword sensing, slacking reminders, late-night mode, weather effects, etc.

Weather requires filling in the city in settings (API Key optional); Open-Meteo is free and doesn’t need a Key; leaving the city blank disables internet access. When weather effects are enabled, full-screen ambiance like rain, snow, or lightning switches based on real weather, and automatically reduces intensity in working mode.

Engineering Features¶

The core state machine (whale-moe-core.js) is separate from the DOM presentation layer; the installation script includes backup and rollback features; resource URLs include version numbers for cache busting. The repository contains 97 unit tests, plus CDP and animation QA scripts for secondary development reference.

Installation and Activation¶

Prerequisites: Windows 10 / 11 (official development and testing environment), Node.js 18+ (required for script installation), latest Edge / Chrome. The script method will rewrite frontend resources in the DSH installation directory; it’s recommended to close the DSH page first and note the current DSH version; please retain the Backup: path from the installation script output until verification is complete.

The DSH installation directory typically contains DeepSeekHarness-Launcher.exe and node_modules; if unsure, you can read the workDir from the launcher configuration:

Get-Content "<DSH_INSTALL_DIR>\DeepSeekHarness-Launcher.cfg"

Method 1: Bundle Package Installation (Zero-Intrusion, Recommended for New Users)¶

The plugin declares dsh.bundle.patch and can be installed directly using the DSH plugin command, without needing a script to modify built-in packages:

dsh plugin --profile web add github:Sutera-Diffusus/dsh-whale-musume

After installation, restart dsh web, open DSH in the browser (default http://127.0.0.1:3080), force refresh (Ctrl + F5), and the whale musume should appear in the bottom-right corner. In this mode, the host only registers the /api/dsh-whale-musume/assets static resource route, with the body injected on the browser side; the gear menu and localStorage (key prefix whale-moe:) manage switches and nurturing data.

Method 2: Release Script Installation (For Theme Integration Scenarios)¶

First, perform Step 1: download dsh-whale-musume-plugin-vX.Y.Z.zip from Releases and extract it, for example to D:\dsh-whale-musume.

Then, perform Step 2: execute the two installation commands in the plugin directory:

node scripts/apply-theme.mjs --assets-only --target "<DSH_INSTALL_DIR>"
node scripts/apply-theme.mjs --mascot-settings --target "<DSH_INSTALL_DIR>"

You can also specify the directory using an environment variable:

$env:DSH_INSTALL_DIR = "<DSH_INSTALL_DIR>"
node scripts/apply-theme.mjs --assets-only
node scripts/apply-theme.mjs --mascot-settings

After these steps, refresh the DSH page and verify: single-click triggers blushing effects, triple-click triggers starry-eyed reactions, dragging switches the picked-up posture, and the settings page shows the “Mascot” section.

Choose one of the two installation methods; do not mix them. To temporarily disable, turn off the “Mascot” switch in settings; resources remain in place.

Typical Usage¶

Dragging and Positioning¶

Hold and drag the whale musume to move it; release to save the position to localStorage; right-click → Return to Original Position to restore the default bottom-right corner.

Right-Click Menu¶

Update and Rollback¶

Update: download the new version zip, overwrite assets/ and scripts/, re-execute the two script installation commands, then force refresh.

Rollback example:

node scripts/apply-theme.mjs --rollback "<backup dir>"

When uninstalling script injections, execute apply-theme.mjs with --rollback once each for settings and resources; for bundle mode, follow DSH plugin management procedures to remove.

Applicable Scenarios and Notes¶

Suitable for developers who want lightweight companionship in the DSH web interface without opening additional windows. The working state interacts with DSH task flows, and the slacking mini-games and achievement system are ideal for long-duration monitoring scenarios; when you need to minimize distractions, you can turn off dialogue bubbles, late-night mode, or the entire mascot switch.

Important notes:

1. The plugin runs with the DSH process and browser context. Before installation, please read the source code and MIT license to confirm you accept the script rewriting frontend resources or bundle injection methods.
2. The official testing environment is Windows; other systems require manual verification of script and bundle compatibility.
3. Regarding privacy, the README states that telemetry and data uploads are disabled by default; nurturing data is stored in localStorage (prefixed with whale-moe:) and does not contain API keys or credentials. Weather-related requests are only initiated when you actively configure a weather city or API key.
4. If the whale musume doesn’t appear after refreshing, confirm the installation output includes Applied, force refresh, and check the “Mascot” switch; if the settings page lacks the section, verify DSH version compatibility and execute --mascot-settings.

Conclusion¶

dsh-whale-musume integrates the mascot, task state interaction, local nurturing, and mini-games into a single DSH page, accessible via bundle or script methods. If you’re browsing DSH plugins on SkillHub or GitHub, consider it a feature-complete desktop pet solution in the “Fun Costume Changes” category.

• Community Directory: SkillHub - dsh-whale-musume
• Source Code and Documentation: GitHub - Sutera-Diffusus/dsh-whale-musume