Preface¶

When running long-running tasks with DeepSeek Harness (dsh), you often have to switch back and forth between your editor and terminal. Although the web interface displays tool calls and streaming outputs, you still have to manually check the conversation content to determine whether the agent is currently executing, thinking, waiting for your approval, or has already finished. If the window is covered after the task completes, you can easily miss the notification.

dsh-kun-like-pet turns this into a desktop pet in the bottom-right corner: Little Kun will switch animations based on the agent’s working status, and play a clip of “Ni gan ma~ ai yo” when a task cleanly finishes. It doesn’t solve the problem of writing code itself, but adds a visible and audible status feedback layer for the current dsh session.

This article is organized after cross-checking with the community directory page, GitHub repository README/CHANGELOG/source code, and the official DeepSeek Harness repository. The directory site is an independent community project and has no affiliation or endorsement relationship with DeepSeek or Magic Square. DeepSeek Harness itself adopts an “everything is a plugin” architecture and is currently in the developer preview stage.

What is this¶

dsh-kun-like-pet is a fun DeepSeek Harness plugin maintained by liyupi, open-sourced under the MIT license, and primarily written in JavaScript. It was added to the community directory on 2026-08-15, and the repository was created on 2026-08-14. As of 2026-08-17, GitHub shows 47 stars (it showed 26 when first listed on the directory page).

One-sentence positioning: It places a Little Kun desktop pet in the bottom-right corner of the DSH web interface, polls the agent’s running/idle status, switches 9 different animations in conjunction with tool execution, approval, and error events, and plays a completion sound from the host process when a task finishes.

The repository README states that the desktop pet is developed and tested as a DSH dynamic plugin (cordis_define), and is split into a Host half and a Client half:
- Host (src/host.js): Reads local spritesheet and voice files, registers HTTP routes, runs the state machine, plays completion sounds via system commands, provides the pet-state RPC and kun_pet_debug tool
- Client (src/client.js): Injects shell.overlay, renders animations in the bottom-right corner, supports dragging and clicking

The current version is recorded as v5 in the CHANGELOG. The code version number in package.json is 1.0.0.

Core Features¶

9 State Animations¶

The assets fully follow the Codex desktop pet spritesheet convention: a single 1536×1872 WebP image with a grid of 8 columns × 9 rows, with each cell being 192×208. Animations are implemented using CSS background-position to select frames, with no additional redrawing. The repository’s assets/spritesheet.webp and docs/SPRITESHEET-CONTRACT.md clearly document the row and column conventions.

The host state machine outputs a mode value, which the client maps to a row in the spritesheet. The corresponding relationship given in the repository README is as follows:

You can drag it around the window, and clicking it will make it wave to say hello. The click interaction sound uses the browser’s Audio API; the task completion sound does not go through the browser to avoid playing twice from a single click.

Perceiving Agent Status via Polling¶

The Host polls the agents service every 500ms by default, reading the status (running/idle) of each agent. The five modes of working, thinking, waiting, error, and idle, are derived together with tools/execute, approval/request, and agent/request-error events.

The CHANGELOG v3/v4 records why pure event listening is not used: the author used the internal/dispatch probe to count 831 bus events, among which status events such as agent/status and agent/turn-stopping were 0. The bus where the dynamic plugin resides is isolated from the distribution path of these events, so listening to events alone will never wait for a “task completed” signal. Polling the agents service is the documented cross-deployment solution in the repository.

v5 loosened the celebration condition to: any agent cleanly ends its turn (running → idle), with no other agents running and no pending user input. The sound will not play a second time while the celebration animation is running.

Completion Sound via Host Process¶

When a task completes, the Host executes a system playback command via the shell service, which defaults to afplay on macOS. The README states that any window or session completing a task will play the sound locally, regardless of whether the browser is muted.

Windows/Linux users need to modify the playCommand. The repository provides the corresponding syntax:
- Windows: powershell -c (New-Object Media.SoundPlayer '…').PlaySync()
- Linux: ffplay -nodisp -autoexit '…'

Debug Tool kun_pet_debug¶

The Host registers a diagnostic tool kun_pet_debug for viewing internal state machine counts and polling health metrics, such as the current mode, celebration count, tool execution count, polling count, and the most recent playback error. The README clarifies that it is only for troubleshooting pet behavior, not a daily conversation tool.

Installation and Activation¶

The installation command given on the community directory page is:

dsh plugin add github:liyupi/dsh-kun-like-pet

For reproducible installations, the directory page recommends pinning the commit hash. The latest commit on the current main branch is 87bb6e1762618dd7727d285ffeeadd86a3799425 (2026-08-14):

dsh plugin add github:liyupi/dsh-kun-like-pet#87bb6e1762618dd7727d285ffeeadd86a3799425

When specifying a profile, the official documentation uses the syntax dsh plugin --profile <name> add github:owner/repo.

There are two things to note separately. The directory page treats this dsh plugin add command as the general installation entry point; the repository README instead documents the tested path as a dynamic plugin: using cordis_define to inject the Host/Client code, then activating it with cordis_run. The current package.json only has a test script, no prepare, and no dsh bundle package fields declared. If the desktop pet does not appear in the bottom-right corner after installing via the directory command, follow the dynamic plugin installation steps from the README below.

Method 1: Dynamic Plugin (Recommended by Repository, Tested)¶

1. Clone the repository:

git clone https://github.com/liyupi/dsh-kun-like-pet.git

2. Modify the CONFIG at the top of src/host.js. The default paths in the repository point to the maintainer’s local machine (/Users/yupi/.codex/pets/... and ~/Downloads/你干嘛哎呦.mp3), which must be changed to your own absolute paths after switching machines. The README installation example points to the assets in the repository:

const CONFIG = {
  spritePath: '/your/path/dsh-kun-like-pet/assets/spritesheet.webp',
  voicePath:  '/your/path/dsh-kun-like-pet/assets/voice.mp3',
  // macOS uses afplay by default; change to the corresponding playback command for Windows/Linux
  playCommand: (path) => "afplay '" + path.replace(/'/g, "'\\''") + "'",
}

3. Generate the cordis_define payload:

node scripts/build-kunpet-package.mjs -

The output is a JSON object. kind: "new" means creating a new plugin, and subsequent updates will use kind: "existing" with the pluginId included. The payload structure is as follows:

{
  "plugin": { "kind": "new", "idPrefix": "kunpet" },
  "name": "Kun Like 桌宠",
  "purpose": "在 Web 界面右下角显示 Kun Like 桌宠，随 Agent 工作状态切换动作，任务完成时播放「你干嘛~哎哟」语音。",
  "code": { "host": "<src/host.js 内容>", "client": "<src/client.js 内容>" }
}

4. Pass this JSON to the cordis_define tool in the DSH session (you can also have the agent execute it for you), then activate it with cordis_run. The desktop pet should appear in the bottom-right corner of the web interface.

Before installing, you can run the built-in script for integrity checks:

node scripts/validate.mjs

It will check if the spritesheet is a valid WebP, if its dimensions are 1536×1872, and if the Host/Client code conforms to the dynamic plugin format.

Method 2: Preview Animations Without Installing DSH¶

Open demo/index.html to view all 9 animations and test dragging and clicking. The README recommends starting a static server, for example:

npx serve .

Or:

python3 -m http.server

Typical Usage¶

After installing and activating, no additional slash commands are needed. The desktop pet will follow the agent in the current session:
1. Assign a task that calls tools to the agent (writing files, running commands, etc.). The bottom-right corner will switch to “Working hard…”.
2. When the tool pauses temporarily and the model is still in the turn, it will switch to “Thinking…”.
3. When approval is required or you need to reply, it will switch to “Waiting for your reply~”.
4. When the turn cleanly ends (running → idle, with no other agents running and no pending input), “Ni gan ma~ ai yo” will play, and the animation will alternate between waving and jumping for approximately 4.8 seconds (default celebrateMs is 4800).
5. When a request errors, the sad animation will last approximately 2.6 seconds (default failedMs is 2600).

All adjustable parameters are in the CONFIG at the top of src/host.js:

After modifying the CONFIG, you need to regenerate the payload and run cordis_define again. If the pet behaves abnormally, call kun_pet_debug in the session to check if mode, pollCount, and lastPlayError are updating.

Applicable Scenarios and Notes¶

This plugin is suitable for users who already use the DSH web UI and want to add status prompts for long-running tasks; it is also suitable for developers who want to learn how to write dynamic plugins (Host/Client, shell.overlay, polling the agents service). It does not provide new coding capabilities and will not speed up tasks themselves.

Before using, please note these boundaries, all from the repository README, CHANGELOG, and source code:
1. Dynamic plugins are session-bound. The pet interface is only injected into the single session page where it was activated. Starting from v5, the completion sound is played by the host process, so other windows or sessions completing tasks will also play the sound locally, but the pet will not appear in all windows. The README states that to make the pet appear in all windows, you need to upgrade to a host bundle-level plugin package.
2. Asset paths and playback commands must be modified for your local machine. The source code defaults to macOS + afplay. If you do not modify playCommand on Windows/Linux, the completion sound will not play. If the spritesheet fails to load, the Client will fall back to displaying an emoji placeholder.
3. Completion sound depends on the shell service. The Host uses ctx.get('shell') to execute the playback command; if this service is not available, lastPlayError will record shell service unavailable.
4. Asset copyright and code license are separate. The code is MIT licensed. assets/voice.mp3 is a publicly available secondary creation meme audio (including a public figure’s voice), and the copyright belongs to the original author. The README states that it is for personal learning and communication only, do not use commercially; replace it with royalty-free materials if you need to use it commercially. assets/spritesheet.webp is a fan-made pixel character following the Codex desktop pet convention. If the rights holder wishes to have it removed, please contact the repository maintainer.
5. The plugin runs with the permissions of the current dsh process. Both the directory page and the official installation documentation remind you that installing the plugin may execute code, and it is not in the agent sandbox. Before installing, you should check the source code repository and license; for reproducible installations, pin the commit hash. Only authorize packages whose source code you trust.

Summary¶

dsh-kun-like-pet maps the agent’s working, thinking, waiting, error, and completion states to 9 animations of Little Kun in the bottom-right corner, and plays the completion sound via the host process. It is a community fun plugin and not a product in the official app store. The general installation command on the directory page is dsh plugin add github:liyupi/dsh-kun-like-pet; the currently tested path in the repository is to modify CONFIG and then use cordis_define / cordis_run.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-kun-like-pet/

GitHub: https://github.com/liyupi/dsh-kun-like-pet