Back to directory

dsh-pet-whale

In a curated listMaintenance: Active

nzl153/dsh-pet-whale

Show idle, thinking, working, waiting, error, and completion states as an interactive whale companion in DSH.

View on GitHubHomepage
$ dsh plugin --profile web add link:/path/to/pet-whale

14

stars

3

forks

JavaScript

Language

MIT

License

2026-08-14

Created

2026-10-02

Last push

MIT-licensed DSH desktop pet: a zero-dependency DOM whale that mirrors idle / think / working / celebrate / error / wait states across desktop and web, added to the profile `package.json` dependencies plus `dsh.profile.bundles` and activated with `pnpm install`.

DSH integration

Native runtime

Author-claimed

Safety audit

Unaudited

Last verified

2026-11-13

License

MIT

01What can it help you accomplish?

  • See at a glance what DeepSeek Harness is doing — idle, thinking, working, waiting, errored or celebrating — from a desktop pet in the corner

    A whale whose animation and face follow the session state machine (idle / think / working / celebrate / error / disappointed / wait, priority error > celebrate > think > working > idle) on both the desktop app and the web UI

    DSH users who run long agent turns and want an ambient status indicator instead of watching the transcript

  • Keep an eye on several concurrent sessions and be told when one finishes

    The whale keeps working while another session runs, shows a bubble badge with the number of running sessions, celebrates and names the session that finished, and reminds you which session is waiting for input

    People who keep parallel DSH sessions open (DSH 0.1.7 and newer for this feature)

  • Turn a long DSH session into something you can poke at, restyle and hide

    Poking, petting, double-click flips, drag with edge squashing, a seven-palette skin picker, 0.8–1.6× sizing, WebAudio sound effects, hide-to-corner with a draggable status button, and light/dark theme following

    Users who want the harness to feel less like a terminal and more like a desktop app

02How to install into DeepSeek Harness

Prerequisites

  • DSH `>=0.1.5-alpha.2 <0.3.0` and Node.js `^22.19.0 || >=24.0.0`
  • The profile directory you actually run — desktop and web each use their own profile; the web one is usually `~/.dsh/profiles/web`

Installation steps

  1. 01

    Edit the profile `package.json`: add `"pet-whale": "^1.2.7"` to `dependencies` and `"pet-whale"` to the `dsh.profile.bundles` list next to the existing entries

  2. 02

    Run `pnpm install` in that profile directory, then restart DSH — on desktop quit from the tray and start it again

  3. 03

    Alternative: install without npm — `dsh plugin --profile web add link:/path/to/pet-whale` for a local checkout (the repo already ships the built `lib/`), or `dsh plugin --profile web add "github:nzl153/dsh-pet-whale#main"` for a git install

    $ dsh plugin --profile web add link:/path/to/pet-whale

Verify the integration

Not specified by the author

03DSH integration and capability boundaries

DSH integrationNative runtime

DSH plugin bundle with a client half (`lib/client.js`) that renders the whale in the DSH UI and follows session state, plus a host half (`lib/index.mjs`); it is added to the profile's `dsh.profile.bundles` list

  • Agent state machine

    DSH session snapshots and chat projection (`running`, `lastAgentError`, `partial`, `runningCalls`, `turnEnds`)→idle / think / working / celebrate / error / disappointed / wait animation with priority error > celebrate > think > working > idle

  • Follow all sessions

    per-session running and pending-approval status from `ctx.uiSession.sessionStatus`→a bubble badge with the number of running sessions, a celebration naming the session that finished, and a reminder of which session is waiting (sub-agents excluded)

  • Thinking stream bubble

    the model's most recent reasoning text while the state is `think`→the last ~200 characters scrolling slowly above the whale, toggleable from the context menu

  • Interaction and appearance

    clicks, double-clicks, drags, cursor proximity and context-menu choices→poking / petting reactions, 360° flips, edge squashing, seven palettes, 0.8–1.6× size, six WebAudio sound effects, hide-to-corner with a draggable status button

    remembers position, hidden state and preferences in `localStorage`plays synthesized audio unless muted
  • Locale, theme and power behaviour

    the DSH locale service, the DSH light/dark theme, and page visibility→Chinese / English copy that follows the DSH locale, bubbles and shadows that follow the theme, and animations paused while the page is in the background with a `prefers-reduced-motion` static fallback

04Who is it for? When not to use it?

Good for

  • DSH users who run long agent turns and want an ambient status indicator instead of watching the transcript
  • People who keep parallel DSH sessions open (DSH 0.1.7 and newer for this feature)
  • Users who want the harness to feel less like a terminal and more like a desktop app

Not for

  • The plugin is pinned to DSH `>=0.1.5-alpha.2 <0.3.0`, and several behaviours depend on the host version — following all sessions needs DSH 0.1.7, and the README records 1.1.0 throwing on 0.1.5 and 1.1.2 sitting idle on 0.1.7.
  • Installation is a profile edit, not a one-line add: add the dependency and the `pet-whale` bundle to the profile `package.json`, run `pnpm install` in that directory and restart DSH (desktop must be quit from the tray). Desktop and web each have their own profile, so the edit is per profile.

05Compatibility, maintenance and safety notes

  • The plugin is pinned to DSH `>=0.1.5-alpha.2 <0.3.0`, and several behaviours depend on the host version — following all sessions needs DSH 0.1.7, and the README records 1.1.0 throwing on 0.1.5 and 1.1.2 sitting idle on 0.1.7.
  • Installation is a profile edit, not a one-line add: add the dependency and the `pet-whale` bundle to the profile `package.json`, run `pnpm install` in that directory and restart DSH (desktop must be quit from the tray). Desktop and web each have their own profile, so the edit is per profile.
  • The whale outline uses DeepSeek's official FishLogo path, which the README treats as brand material that must be credited when reused.
  • Hot reload only works when the profile installs this repo via `link:` on DSH `>=0.1.5-alpha.2`; changes to `package.json` structure, `cordis.patch.yml`, the host half or the bundle list still require a DSH restart.
2026-08-142026-10-02v1.2.7

MIT · latest release v1.2.7 (2026-10-02), README evidence only, safety not audited

06Frequently asked questions

How do I install pet-whale into DeepSeek Harness?

Open the profile directory you actually run (desktop and web each have their own; the web one is usually `~/.dsh/profiles/web`) and edit its `package.json`: add `"pet-whale": "^1.2.7"` under `dependencies` and `"pet-whale"` to the `dsh.profile.bundles` list alongside the existing entries. Then run `pnpm install` in that directory and restart DSH — on desktop, quit from the tray and open it again.

Is there a way to install it without editing package.json?

Yes, if you have a checkout or prefer a git install: `dsh plugin --profile web add link:/path/to/pet-whale` for a local directory (the repo already ships the built `lib/`, so no build step) or `dsh plugin --profile web add "github:nzl153/dsh-pet-whale#main"` for git. The `link:` route is also the only one that supports the README's hot-reload workflow.

Which DSH versions does it work with?

DSH `>=0.1.5-alpha.2 <0.3.0` and Node.js `^22.19.0 || >=24.0.0`. Some features need newer hosts: following all sessions needs DSH 0.1.7, and the README documents 1.1.0 throwing on 0.1.5 and 1.1.2 sitting idle on 0.1.7 — 1.1.3 fixed that by reading the session held by the main view.

Does the pet read my conversation content?

It reads session state to pick an animation — the session snapshot (`running`, `lastAgentError`) and the chat projection (`partial`, `runningCalls`, `turnEnds`) — and, while the state is `think`, it scrolls the model's most recent ~200 characters of reasoning above the whale (toggleable from the context menu). Everything renders locally in the DSH page; position, hidden state and preferences are kept in `localStorage`.

What files does it write, and does it need audio assets?

It is plain DOM with no React and no third-party runtime dependencies, and the six sound effects are synthesized with WebAudio, so there are no audio files to ship. The only client-side state it stores is `localStorage` preferences such as position, size, palette, mute and hidden state.

08Data and sources

  • Author-claimedgithub.com231a1936c427…

    DeepSeek Harness(DSH)的桌宠插件,桌面端和网页端都能用:右下角一只**官方轮廓版小鲸鱼**,随 agent 状态实时切换动画。纯 DOM 实现、零 React 依赖、零运行时第三方依赖,WebAudio 合成音效无音频文…

  • Author-claimedgithub.com231a1936c427…

    在你正在用的 profile 目录(桌面端和网页版各用各的 profile,网页版一般是 `~/.dsh/profiles/web`)的 `package.json` 里加上依赖和 bundle:

  • Author-claimedgithub.com231a1936c427…

    "dependencies": { "pet-whale": "^1.2.7" }, "dsh": { "profile": { "bundles": ["...原有的...", "pet-whale"] } }

This page is generated from the project’s public documentation, repository metadata and a structured parse of DSH Plugins; last verified on 2026-11-13. Found an error? Submit a correction.

🏆

Best DeepSeek Harness Plugins

Twelve plugins worth installing first — picked from the whole catalog, across every category.

DSH Plugins is an independent community directory of DeepSeek Harness plugins. Not affiliated with or endorsed by DeepSeek. Third-party plugins are not security-audited — review the source before installing.

New DeepSeek Harness plugins, weekly. No spam.