dsh-pet: a transparent desktop pet for DeepSeek Harness, installed with one plugin command

What dsh-pet actually solves, and who it is for

dsh-pet is a plugin for DeepSeek Harness, the dsh CLI and web interface. It draws an animated character in a transparent overlay, either inside the browser or in a separate always-on-top window, and it reacts to what the harness is doing: session events, balance refreshes, and a chat channel. The README is explicit that it is a pet and nothing else, stating that it does not do weather or monitoring and does not touch the DSH kernel. That restraint matters. Plugins that hook into an agent runtime tend to grow side effects; this one keeps its optional surface to balance display, idle chatter, chat, work status and system notifications.

The audience is narrow and specific. You need dsh installed, you need the web profile, and you need to be comfortable editing a JSONC config file if you want anything beyond the settings page. The README describes the project as a three-part set: a prompt recipe, an asset generation chain that turns source video into transparent animations, and the plugin itself. Someone who only wants a pet on screen uses the third part. Someone who wants a different character uses all three, and that second audience is clearly the one the repository is built around, given the prompts/, video/, tools/ and scripts/ directories at the top level.

The animation chain and how a pet decides what to do next

Every animation, including the idle one, plays to completion and then picks its successor by weight. The README gives the defaults as idle 10, turn 5 and move 5 plus per-category weights, all adjustable in config.jsonc. Switching between clips uses double buffering with a cross fade, which the README says avoids blank frames. That is the whole runtime loop, and it is worth understanding before you touch weights: raising a category weight does not make that category start sooner, it only makes it more likely to be chosen at the next boundary.

Event animations are separate from that chain. Balance, chatter and work status each map to a slot, and any slot can hold either a single animation name or an array. An array means one is drawn at random when the slot fires, and repeated play rotates through the array so the same clip does not run twice in a row. The work status array is indexed by state, and the README warns against inserting entries in the middle, only appending at the end, because the index is the state. That is a real constraint: reordering the array silently remaps 思考, 工作, 整理, 等待, 成功 and 出错 to the wrong animations.

Movement is not scripted per animation. The README describes roaming as walking in the facing direction after probing the space first, so the pet does not walk off screen, with multi-monitor boundaries evaluated per screen. Mirroring is available for all animations so a pet can face left or right, and the foot line is unified so it always stands on the ground.

Installing dsh-pet and getting the first pet on screen

The README puts every install command in your own terminal, PowerShell or CMD, and lists the prerequisites as an existing dsh environment. First confirm Node.js is present, then install the dsh launcher and pnpm globally. The README notes you can skip this step if both are already installed, and that you should reopen the terminal afterwards so the new commands are on PATH.

node -v
npm install -g @deepseek-ai/dsh pnpm
dsh --version

If dsh --version prints a version, the launcher is usable. The README states the plugin was developed and tested against dsh 0.1.5-rc.1 and recommends matching that version, so compare the output before continuing rather than after something breaks.

dsh plugin --profile web add dsh-pet

That is the entire install. Restart dsh web and the pet appears in the upper right of the interface. The README says the default position is the corner and that it can be changed on the settings page. If you would rather build from source, the repository expects a build first, because the README states the lib/ build output is not committed. Clone the repository, enter the dsh-pet subdirectory, install dependencies, then run the prepare script, which the README says produces the full installable lib including the desktop shared core and type declarations. A bare tsdown build is described as missing the desktop runtime and the types.

git clone https://github.com/PC2005-cloud/dsh-pet.git
cd dsh-pet/dsh-pet
npm install
npm run prepare
dsh plugin --profile web add file:D:/path/to/dsh-pet

The file: target points at the directory you just built. Note the doubled dsh-pet path in the README example: the repository root and the plugin package share a name, so the clone lands in dsh-pet and the plugin lives in dsh-pet/dsh-pet.

Desktop mode, display values and where it refuses to work

The plugin ships two rendering modes. The browser overlay is the baseline. Desktop mode opens a separate transparent always-on-top window per pet that follows the pet around rather than covering the screen, and the README states it shares the same assets and pure logic as the browser path, with the physics in dsh-pet/src/shared/physics.ts. Which one you get is controlled by a required per-pet field named display, with four values: web for browser only, desktop for desktop only, both, and none. Desktop mode renders every pet whose display value includes desktop, so multi-pet setups behave the same in both modes.

Electron is downloaded automatically on first launch into ~/.dsh/electron/, or you can trigger it manually with npm run ensure:electron from the dsh-pet directory. If the download fails, the README says you get a log warning and the browser overlay is unaffected, which is a sensible failure mode. Headless Linux is handled the same way: with no DISPLAY or WAYLAND_DISPLAY the plugin skips the desktop window and logs a warning.

Browser support is the sharpest limitation in the README. Transparent animation depends on VP9-Alpha webm, and the README states Chromium and Firefox both render it correctly while Safari does not, because macOS does not honour webm alpha and draws a black background. The workaround is a separate .mov asset set published as assets-mov on GitHub Releases, dropped in with the ANIMATION_EXT variable changed. That is a real manual step, not a flag, and it is the point where a macOS user on Safari should stop and reconsider.

Balance, work status and the credential you have to supply

Balance display polls the current provider on the interval set by eventsRefreshSec.balance, plays a tiered animation and shows a bubble above the pet that disappears after 10 seconds. Two providers are registered. For deepseek-official the bubble shows the account balance and the tier is computed from a percentage used against a 20 yuan full amount, across six tiers. For opencode-go the bubble shows whichever of the 5-hour, weekly or monthly windows is closest to exhaustion. Credentials come from DSH credentials: DEEPSEEK_API_KEY or OPENCODE_GO_API_KEY respectively.

Anything else is handled by refusing to guess. The README states that unregistered providers do not play a tiered animation and instead show a text bubble whose first line says the provider does not support balance queries and whose second line reports the provider id, with the same treatment for missing credentials or a failed fetch, where the reason goes on the second line. Automatic polling only shows the bubble when the reason changes, so it does not nag, while a manual /balance or the desktop context menu item shows it every time. This is a better design than a silent no-op, and it is the kind of detail that tells you the author has been bitten by an empty bubble before.

Work status is gated by pets[i].workStatusEnabled and maps six harness states to animations. Non-terminal states loop with a persistent bubble; success and error play once and the bubble collapses after 10 seconds. Bubble text can be configured per tier with multiple candidates chosen at random, and task detail takes priority when present. The README notes that multi-round tasks only celebrate on the genuinely final round.

Pet packs, custom animations and the DIY generation chain

Two extension paths exist without touching the plugin source. Dropping a VP9-Alpha .webm into main-animation/webm/ adds an animation, and the README says files placed there take priority over the bundled assets. A pet pack is heavier: create a 种类名-config.json file and a matching 种类名-animation/ directory under pet/, and you have a new species with its own animation pool. Multiple instances of the same species share the assets.

Beyond that is the part the repository is organised around. The top-level layout includes prompts/, video/, tools/ and scripts/ alongside dsh-pet/, and the README describes the flow as prompt recipe, then an asset chain turning source video into transparent animation, then the plugin. The claim is that anyone who clones the repository can generate a pet from scratch with a different character, different actions and a different style, reproducibly. That is the most interesting thing here and also the least documented in the README: the pipeline is referenced and the directories exist, but the README does not walk through the generation steps the way it walks through installation. Expect to read the files in prompts/ and scripts/ directly rather than following a tutorial.

Chat and chatter are the softer features. Whisper is off by default and gated by pets[i].whisperEnabled with a default period of 300 seconds per pet, each with its own text. The context menu item bypasses that gate, so manual whispers work even when automatic ones are off. Chat opens an input box from the context menu or the /chat command, replies use the same animation and bubble treatment, and memory persists to $DSH_HOME/dsh-pet/memory.json shared between browser and desktop. With multiple pets you select the target with /pet first.

Maintenance, licence and what a version bump costs you

The repository is not archived, and the last push was on 2026-09-16, the same day as the v0.2.10 release. Releases v0.2.8, v0.2.9 and v0.2.10 landed on 2026-09-11, 2026-09-14 and 2026-09-16 respectively, so the release cadence in that window was roughly every few days. That is a fast-moving project, and fast-moving projects have a cost: the README pins compatibility to dsh 0.1.5-rc.1, a release candidate. If your dsh is newer, you are outside the tested combination, and the README asks for feedback rather than promising support.

Upgrading is a plugin command plus a dsh web restart. The desktop side adds a second moving part, since Electron is downloaded per machine into ~/.dsh/electron/ and can be re-fetched with npm run ensure:electron. A source install adds a third, because lib/ is not committed and npm run prepare must run before the plugin is usable.

The licence is MIT, which is permissive and compatible with commercial use, and the repository carries a LICENSE file at the top level. Nothing in the README addresses a separate licence for the animation assets or the mov asset set on GitHub Releases. If you plan to redistribute the bundled animations or generated pet packs, that is the question to resolve with the author, not something to assume from the MIT badge. This is not legal advice; read the LICENSE file and ask.

Editorial conclusion

Adopt dsh-pet if you already run DeepSeek Harness and want a pet overlay that stays out of the kernel, or if you want to generate your own pet pack from source video through the prompts and scripts in the repository. Skip it if you need Safari support, if you are on dsh 0.1.5-rc.1 and unwilling to pin that version, or if you want a pet outside DSH entirely. Before installing, run dsh --version and confirm it reports 0.1.5-rc.1, since the README states that is the only version the plugin was developed and tested against.

Frequently asked questions

Official sources

1. License: MIT
2. PC2005-cloud/dsh-pet on GitHub
3. Project website
4. README
5. Releases