Preface¶

When running Agents with DeepSeek Harness (dsh), to check whether the agent is currently thinking, invoking tools, or has finished or encountered an error, you typically have to stare at the conversation stream in the Web page. dsh-pet adopts a different presentation method: it maps the agent’s real-time events into a desktop pet animation, switching states as events occur, so a quick glance at the corner of the page reveals the current progress.

Below is an introduction to the plugin’s features, installation methods, and typical usage.

What is it¶

dsh-pet is a DSH plugin maintained by levi52. In short, it is a Codex-style DeepSeek Harness desktop pet: it embeds the DSH Web interface and plays animations in sync with the agent’s real-time status. Both sprite sheets and animation timing can be visually configured in the settings page. The project is licensed under the MIT license.

Technically, it does not modify the core dsh: it injects the pet overlay into dsh’s 3080 Web page via the official webServer.tapIndex, sharing the same origin and page, appearing and disappearing together.

Core Features¶

• Event-driven animation: Subscribes to the root context’s session/event, switching between six animations (idle, thinking, executing, waiting, finished, failed) based on events such as turn/start, tool/call, and turn/end.
• Sprite sheets as configuration: The grid layout of the sprite sheet and the ‘state -> row’ mapping are declared in the configuration (config.sprite or a sidecar file with the same name .json). Changing the sprite image requires no source code modification.
• Settings page management: The dsh settings page has a ‘Pet’ section allowing visual configuration for uploading/selecting sprite sheets (webp/png/gif/jpg/svg), grid, state mapping, scaling, animation speed, idle delay, and visibility.
• Hot push configuration: Changes are pushed to the renderer via SSE config events. Adjustments to scaling, animation speed, and idle delay take effect immediately without needing a refresh or restart.
• Automatic persistence: Settings are saved to pet/user-config.json and automatically restored after a refresh, taking precedence over cordis.patch.yml.
• Multiple presentation forms: In addition to the embedded overlay, it also provides a standalone popup page, a Chrome app borderless window, a pywebview transparent window (packable as .exe), and Electron.

Installation and Enablement¶

There are two environment requirements:

• DeepSeek Harness (dsh CLI) is installed and a Web profile has been run.
• Node.js ≥ 18.

Installation consists of two steps. First, register the local plugin directory to the web profile:

dsh plugin --profile web add <本目录路径>

Second, start dsh, which will also launch the Web GUI:

dsh --profile web

After the above steps, open the Web address printed in the terminal (usually http://127.0.0.1:3080/), and a desktop pet will appear in the bottom right corner of the page; the management entry is in Settings → Pet.

To uninstall, run:

dsh plugin --profile web remove dsh-pet

Note: User data (pet/user-config.json and pet/uploads/) will be retained after uninstallation; manual deletion is required for a thorough cleanup.

Configuration¶

The default configuration works out of the box. To override default values, add the following to the profile’s cordis.patch.yml (top-level YAML array):

- insert:
  - id: dsh-pet
    name: dsh-pet
    config:
      idleMs: 3000
      scale: 1
      fpsScale: 1
      injectOverlay: true
      overlayRoute: /dsh-pet

Supported configuration items:

• idleMs (default 3000)
• scale (default 1)
• fpsScale (default 1)
• injectOverlay (default true)
• overlayRoute (default /dsh-pet)
• enabled (default true)
• spriteFile (default doraemonsprite.webp)
• sprite (grid layout and state mapping)

Here, sprite declares the grid layout of the sprite sheet and the mapping from states to rows, while spriteFile specifies the sprite image file. Settings saved via the settings page are written to pet/user-config.json, taking precedence over cordis.patch.yml.

Standalone Window Mode¶

In addition to the embedded overlay, the pet renderer also provides a standalone page at the address:

http://127.0.0.1:3080/dsh-pet/

To create a borderless desktop window, you can use Chrome App mode:

chrome --app="http://127.0.0.1:3080/dsh-pet/" --window-size=256x320

You can also launch a transparent window using pywebview:

cd dsh-pet/pet
pip install pywebview
python launch.py

When distribution is required, use pyinstaller to package it into a single-file .exe:

pyinstaller --onefile --windowed --add-data "doraemonsprite.webp;." --add-data "pet.html;." launch.py

The feature list also mentions the Electron form, but specific operation steps are not provided in the README body. Additionally, when not connected to dsh, the standalone page will automatically loop through the state animations (demo mode). Pressing the D key allows manual switching, making it suitable for previewing animation effects individually.

Applicable Scenarios and Considerations¶

Target Audience:

• People who operate Agents via the dsh Web page daily and want to see the status at a glance.
• People who want to add status visualization to their workspace without modifying the core dsh.

Notes before and during use:

1. The plugin runs with the permissions of the current dsh process. Please check the plugin source code and license yourself before installing (this project is MIT).
2. All data is stored locally (in the pet/ directory and dsh profile). Nothing is uploaded, no keys or credentials are collected, and resources are only locally accessible; the sprite upload interface only accepts image formats and performs filename whitelist validation to prevent path traversal.
3. The waiting status is currently triggered manually only in demo mode.
4. How changes take effect: Client-side changes (sprite sheet, scaling, animation speed, etc.) only require a hard browser refresh; Host-side changes (index.js) require restarting dsh.
5. If you plan to do secondary development based on this plugin, note that the client entry in the settings page depends on dsh.client.inject and exports["./package.json"] in package.json. If either is missing, the ‘Pet’ section in the settings page will not appear.

Summary¶

dsh-pet solves a specific problem: turning the Agent’s runtime status from logs into a visible animation at a glance, while making sprite changes and rhythm adjustment pure configuration operations. DSH’s philosophy is “everything is a plugin,” and this non-invasive extension is exactly what this mechanism is good for.

• Plugin Directory Page (Community site, no official affiliation with DeepSeek): https://www.skillhub.cn/plugins/levi52/dsh-pet
• GitHub Repository: https://github.com/levi52/dsh-pet