Introduction

When developing agents with DSH, session progress itself is invisible: turn count, tool call frequency, and continuous usage records are all buried in the Host-side event stream. To add a layer of visual feedback to this data, common approaches are either stuffing state back into the model context or sending data to a remote service; the former wastes tokens, the latter incurs privacy costs.

dsh-whale-companion takes a different path: the plugin only observes submitted session event metadata on the Host side, reads no content, and connects no network, rendering the “Tide, Expedition, Collection” progress system into a draggable desktop whale. Below, I introduce its positioning, features, installation method, and implementation boundaries.

What is it

dsh-whale-companion is a local-first DSH Whale World plugin maintained by LeemanCheung, licensed under MIT. In the directory, it is categorized under the “Fun Dress-up” category. One-sentence positioning: Privacy-safe session metadata turned into a draggable desktop whale companion, complete with 20 unlockable whale sprites, visible tides, personal coves, non-punitive expeditions, and opt-in, local-only whale circle cards.

Version 2.6.0 targets DSH 0.1.2-rc.1, preserving existing names, appearance, position, progress, collections, room presets, and the ImageGen species guide.

Regarding the Model side, it adds no prompts, tools, messages, token usage, or KV-cache content; it only observes submitted session event metadata on the Host and exposes the browser UI.

Core Features

Draggable Desktop Whale

The plugin provides a whale running on shell.overlay, supporting pointer dragging, keyboard movement, and edge snapping; it performs viewport-safe correction when persisting position. The entire UI shares a 5-second local refresh cycle. New tide moments appear in bounded visible bubbles; only milestones notify screen readers.

20 Whale Sprites & XP System

20 unlockable whale sprites are unlocked step-by-step via Ocean Levels 1–100. Each sprite maps its own story and visible tide response to a class of safe events, without changing model behavior.

XP rules are explicit:

  • 10 XP per turn (only user/message counts as a turn)
  • 5 XP per tool result
  • 20 XP at the start of each session

Levels are derived from XP; consecutive UTC session start dates are recorded, and absences do not deduct progress or collections.

Tides, Collections & Expeditions

Tide moments are driven by live-only session/created, user/message, and tool/result metadata and are bounded. Duplicate tool results still count towards existing XP, but cannot be used to farm tide moments, collectibles, or expedition progress.

The Whale Home page provides a seven-day ocean log, current whale story nodes, cove visual preview, and a Privacy Ledger based on real fields. It also features a tide timeline, local PNG postcard export, a 24-item collection catalog, 8 fixed room slots, 3 sets of room presets, and a set of non-punitive expeditions. 6 sets of cove themes adjust background, interface accent colors, and ambient light; whale art retains its own color scheme; all 12 achievements are included.

Sharing: Drift Bottles & Whale Circle Cards

Visitor drift bottles are isolated read-only room previews and will not merge or overwrite the recipient’s progress.

Whale circle cards are opt-in, local-file-only exchanges: they only contain preset alias, species, skin, coarse-grained active bucket, and resonance stars; there are no accounts, network, rankings, free text, prompt excerpts, task names, or tool data.

Presentation Modes & Animation

Three presentation modes—Quiet, Standard, and Lively—are stored in browser local preferences; system reduced-motion is always prioritized, and safe fallback occurs when storage is refused without affecting progress.

2.6.0 introduces a 2.4-second Ink Whale Jump animation: 96 frames at 40 fps, native WebP uses a 25ms uniform frame interval. When reduced-motion is enabled in the system or product, it switches to the corresponding PNG static frame and does not replace the original Dive/Classic state animations.

Installation & Enablement

Install to DSH Web profile:

dsh plugin --profile web add github:LeemanCheung/dsh-whale-companion

After installation, restart the existing DSH Web process and refresh the page to see the whale.

Development Verification & Art Pipeline

If you want to build or verify it yourself, execute the following in the repository root:

corepack pnpm typecheck
corepack pnpm verify:minke
corepack pnpm test
corepack pnpm build
corepack pnpm pack:check

The art pipeline requires installing dependencies first:

python -m pip install -r requirements-art.txt

The pipeline is fixed to Python 3.12, NumPy 2.3.3, and Pillow 12.3.0. corepack pnpm art:minke rebuilds the transparent sprite, and corepack pnpm art:species normalizes the 20 built-in species ImageGen guide in the repository. Visual snapshot baselines are maintained in Ubuntu CI; other platforms still run interaction, animation, reduced-motion, and narrow layout assertions, but do not generate RC screenshot baselines. The production client embeds these raster assets and does not contain runtime vector whale rendering.

Privacy & Implementation Boundaries

This is the part of the plugin that deserves the clearest explanation:

  • The Host only reads session ID, event sequence number, event type, and timestamp; it never reads, stores, exports, or renders prompts, assistant outputs, code, paths, tool parameters, or tool results.
  • In-memory receipt summaries use an HMAC key that does not leave the Host process; the persistent receipt window is capped at 4,096 entries, preventing only recent duplicate deliveries, not permanent replay across Host restarts. Backups deliberately exclude receipt summaries, session IDs, or event data.
  • Background write failures will not interrupt the DSH session; they may only lose that progress update, and subsequent updates will still be accepted; explicit user saves will still report failures.
  • Text import is uniformly limited to 512 KiB before JSON parsing; all persistent writes undergo schema validation.
  • Progress is stored in a single DSH storage backend and does not sync across devices.
  • The overlay polls every 5 seconds because the current Host Remote event allow list does not have a route for whale state push within the package.
  • Whale circle cards deliberately only support local import/export; to have a hosted community, a separate transmission provider that owns, authenticates, and reviews is required.

Applicable Scenarios & Notes

Target readers: People working long-term in the DSH Web environment who want a local-first progress visualization and do not want the plugin to touch prompt content or add any overhead to the model. It is also suitable as a reference implementation for plugin forms like “Host-side metadata observation only.”

Note the following points:

  1. This plugin runs with the permissions of the current dsh process; it is recommended to read the repository source code and LICENSE (MIT) before installation to confirm acceptability.
  2. Progress is not synced across devices; changing machines will not bring progress with you.
  3. The receipt mechanism prevents recent duplicate deliveries, not permanent replay across restarts; this is clearly stated in the README.

Conclusion

dsh-whale-companion demonstrates a restrained plugin form: using only event metadata, keeping all calculation and storage local, zero overhead on the model, turning daily sessions into an accumulatable whale world. If you are building DSH plugins or want to add some fun to your work environment, it is worth a try.

  • Directory: https://www.skillhub.cn/plugins/LeemanCheung/dsh-whale-companion
  • GitHub: https://github.com/LeemanCheung/dsh-whale-companion