Preface¶

DSH’s extension model is “everything is a plugin.” In the community directory, there are small plugins that attach to the DSH web interface: they do not replace Agent workflows, but rather turn status, approvals, notifications, and other information into visible interactions. whale-on-desk is one such example: it provides DeepSeek Harness with a pixel whale desk pet. Below, we introduce its positioning, installation methods, typical usage, and boundary considerations.

What This Is¶

whale-on-desk is a DSH plugin maintained by cookiesheep, positioned as a “pixel whale desk pet for DeepSeek Harness.” It applies to the DSH web interface and is also usable with DSH Desktop. The README status badge marks it as “early preview,” and the license is MIT.

The host side is a Cordis plugin that listens to session/event and exposes /whale/state, /whale/poke, and /whale/assets/* on the DSH web server. The documentation states the plugin is read-only and does not touch sessions or files.

Core Capabilities¶

1. Real-time reflection of Agent status: task running, model outputting, tool calls, approval requests, task completion, and task failure.
2. When approval is requested, the whale sticks to the screen edge, taps the glass, and displays an amber pulse; a notification appears in the browser tab title.
3. On task completion, it performs a backflip celebration and reports elapsed time, tool count, and file count; on task failure, it sinks with its eyes turning into horizontal lines.
4. Can be dragged to any position, and the position is automatically remembered.
5. Sound effects are synthesized in real time with zero audio files.
6. Growth system: completing tasks, starting sessions, and companionship duration accumulate experience, unlocking 8 titles.
7. Provides a whale_say tool that lets the Agent make the whale speak and perform, serving as a notification channel.
8. Aquarium mode: a full-screen aquarium featuring progress corals that grow with tool calls and small fish schools that count this round’s tool calls; when approval is pending, the whale charges at the tank edge and taps the glass.
9. AI Pet Workshop: registers the pet-forge skill, which can generate and hot-swap custom desk pets; requires ffmpeg in PATH.
10. Custom desk pets: place a manifest.json mapping states to GIFs and the GIFs in a designated directory; right-click to switch instantly.

Installation and Enablement¶

First, perform the web version installation:

dsh plugin --profile web add whale-on-desk

Then open or restart the DSH web interface. No API Key is needed, and no additional configuration is required for the web interface.

If using DSH Desktop, the community documentation states that DSH Desktop is an Electron desktop version running the official Web client. First, open Open DSH Terminal from the application tray:

dsh plugin add whale-on-desk

Then restart DSH Desktop.

The current package.json version is 3.0.0. The peerDependencies include:

• @deepseek-ai/cordis
• @deepseek-ai/dsh-client-runtime
• @deepseek-ai/dsh-client-ui-slots
• @deepseek-ai/dsh-host-webserver
• react

Uninstallation:

dsh plugin --profile web remove whale-on-desk

Typical Usage¶

First, verify basic interactions:

1. Hover over the whale to view the current task statistics card, including elapsed time and tool count.
2. Click, single-click, or double-click the whale to trigger startle, squeak, or wake-up reactions.
3. Right-click the whale to open a small menu: mute, return to default position, change desk pet, and hide.
4. After hiding, double-click the restore button in the bottom-right corner to bring it back.

Custom desk pets:

1. Create a directory:

~/.dsh/whale-on-desk/pets/<name>/

2. Place a sprite set: a manifest.json mapping states to GIFs, along with the corresponding GIF files.
3. Right-click the desk pet to switch, taking effect immediately.

AI Pet Workshop:

Simply say to the Agent, “Make me a pink octopus desk pet.” It will design sprite images, generate GIFs, package them as a pet pack, and hot-swap them; this requires ffmpeg in PATH.

Aquarium mode:

Right-click the whale and select Aquarium to enter full-screen aquarium mode; press Esc or the close button to return to desktop companion mode.

Approval and preview:

• When approval is requested, the whale sticks to the screen edge, taps the glass, and displays an amber pulse; a notification appears in the browser tab title.
• For recording demos or taking screenshots, configure allowPreview: true to additionally enable POST /whale/preview.
• Trigger state: {"state":"glass-tap"}.
• Restore: {"state":null}.
• allowPreview is disabled by default.

Sleep timeout:

Configure sleepAfterMinutes in cordis.patch.yml; the default is 10.

Applicable Scenarios and Considerations¶

Suitable for:

• Using the Agent in the DSH web interface and wanting visible alerts for approval waits and task completion/failure.
• Placing Agent status into a desk pet within DSH Desktop.
• Using whale_say to add a lightweight notification channel to the Agent.
• Replacing the default whale with custom GIFs or AI-generated desk pets.

Considerations:

• The plugin runs with the current dsh process permissions; check the source code, license, and dependencies before installation.
• The current license is MIT.
• This plugin has no official affiliation with DeepSeek; the DSH community directory is an independent site and is not equivalent to an official app store.
• The AI Pet Workshop requires ffmpeg in PATH.
• allowPreview is disabled by default; the preview endpoint is only enabled after configuration.
• Specific compatible versions/runtime methods for DSH Desktop are not provided; it is recommended to rely on the actual runtime environment.
• The animation syntax and pixel specifications pay tribute to clawd-on-desk without sharing assets or code; clawd artwork is owned by Anthropic.

Links¶

GitHub: https://github.com/cookiesheep/whale-on-desk

Plugin directory page (from plugin clues, not listed in README/package.json): https://www.skillhub.cn/plugins/cookiesheep/whale-on-desk