Introduction¶

Users of DSH often encounter the same issue: agents often run for minutes or even longer. You switch to another window to work, and the first thing you do is check if it is currently running, waiting for approval, or has stopped with an error. The current workaround is to switch back to the Web GUI and stare at the output, or sift through logs.

silverhand-dsh-pet takes a different approach: handing over status display to a desktop pet. It resides permanently in the bottom-right corner of the DSH Web GUI. It breathes when the agent is idle, works when busy, and throws a tantrum when an error occurs. A glance at the corner is all it takes to know the agent’s status. Below, I introduce the specific features, installation steps, and troubleshooting methods of this plugin.

What is this¶

silverhand-dsh-pet is a standard DSH plugin package. The author is Qiao-NEYC, and the code is released under the MIT license. It renders a character named Silverhand (a cyberpunk mercenary with a silver prosthetic) in the DSH Web GUI’s shell.overlay layer, fixed in the bottom-right corner of the window. It is driven by DSH host events and reacts to agent status.

The assets were migrated directly from the Codex pet format (spritesheet.webp + pet.json). The sprite sheet is 8x9 with 192x208 cells. No redesign was performed.

Core Features¶

Rendered in the shell.overlay layer of the DSH Web GUI, fixed in the bottom-right corner; click-through by default, only the pet itself is interactive and does not interfere with other operations.
Driven by DSH host events. The state mapping is as follows:
idle / running: from agent/status
review: from tools/result
failed: from agent/error
waving: from agent/created and agent/session-start
jumping: triggered when a turn ends (running -> idle)
waiting: during the opening of approval/request
Draggable to move; the pet walks in the direction of the drag.
Hover displays the current state; a single click (without displacement) makes it jump.

Installation and Enablement¶

This is a standard DSH plugin package. The README provides two installation methods, and GitHub installation is recommended.

Edit ~/.dsh/profiles/<profile>/package.json and add it to dependencies and dsh.profile.bundles:

{
  "dependencies": {
    "silverhand-dsh-pet": "github:Qiao-NEYC/silverhand-dsh-pet"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "...your existing bundles...",
        "silverhand-dsh-pet"
      ]
    }
  }
}

Run pnpm install in the profile directory (or let the DSH desktop app install it on startup).
Restart DSH, and the pet will appear in the bottom-right corner.

Another way is npm install: first run npm i silverhand-dsh-pet, then add "silverhand-dsh-pet" to dsh.profile.bundles. Note that the README marks this path as “Once published”, meaning it can only be used after the npm package is published. Currently, the GitHub dependency method above is recommended.

The plugin’s peerDependencies are react ^18.2.0, @deepseek-ai/cordis ^4.0.1, @deepseek-ai/dsh-client-runtime ^0.1.0-rc.6, @deepseek-ai/dsh-client-ui-layout ^0.1.0-rc.6, @deepseek-ai/dsh-client-ui-slots ^0.1.0-rc.6. If you encounter a blank or missing pet image, first confirm that the package version is 1.0.1 or higher (current version is 1.0.2) — since 1.0.1, the client bundle explicitly declares layout dependencies to ensure shell.overlay is available for registration.

How it Works¶

A DSH plugin is a Cordis plugin split into two halves, and this project is no different:

Host Half (lib/index.js): Runs in the DSH Node process. It reads the sprite sheet from its own assets/ directory via import.meta.url (found regardless of where it’s packaged) and registers two same-origin HTTP routes:
GET /silverhand-pet/spritesheet.webp: The sprite sheet
GET /silverhand-pet/state: The derived state from agent events, returning { "state": "..." }
Client Half (lib/client.js): Runs in the browser. It registers into shell.overlay, polls /silverhand-pet/state every 300ms, and plays the corresponding animation row from /silverhand-pet/spritesheet.webp.

Communication between the two halves relies only on ordinary same-origin HTTP routes, with no additional channels.

Configuration and Troubleshooting¶

The plugin has no independent configuration items; all adjustable parameters are constants at the top of the code for both halves:

lib/index.js: ROUTE_SPRITE / ROUTE_STATE, and the transient durations for each state in the event listeners.
lib/client.js: ANIMS (row number, frames, rhythm for each action), STATE_ANIM (mapping from state to animation), PET_W / PET_H (display size), and the CSS block (position, shadow, hover styles).

When troubleshooting a blank or missing pet image, check in the following order:

Confirm that the package version is not lower than 1.0.1.
The Client will probe /silverhand-pet/spritesheet.webp. If the Host half does not provide the sprite sheet normally, the browser console will log a routing error. A 404 or 500 indicates the host bundle is not activated and the bundle needs to be reinstalled and DSH restarted.
Animation frames are reset when switching states to avoid selecting empty cells when switching back to the 6-frame idle or waiting rows — this is built-in protection logic, not a bug.
If the pet container exists but is transparent, open the browser Network panel to check the sprite route: a normal response should be image/webp with a size of about 1 MB.

The repository also includes three development helper scripts. The first two require Python 3, Pillow, and numpy:

# Regenerate docs/demo.gif
python scripts/make_demo_gif.py

# Output the number of opaque cells per row and differences between adjacent frames
python scripts/analyze_frames.py

# Render a contact sheet with annotations (full version + zoomed-in ambiguous rows)
python scripts/contact_sheet.py

Suitable Scenarios and Notes¶

Suitable for two types of people: first, users who keep DSH running in the background for a long time and need to see the agent status without switching windows; second, developers who want to learn the DSH plugin two-half structure (host + client, same-origin HTTP communication, shell.overlay registration). This package is small in size and clear in structure and can be read as a reference implementation.

Before installation, two points must be noted:

The plugin runs with the permissions of the current dsh process. Before installing, check the source code and license. The code part is under the MIT license; however, the license for the sprite assets (the Silverhand image) is not declared in the repository. The assets were migrated from the local Codex pet directory (~/.codex/pets/silverhand/). The README clearly states: before publicly publishing this repository, you must confirm that you hold (or have obtained) the right to redistribute the sprite and the Silverhand image. It is also recommended to self-evaluate before personal local use.
In addition, the community plugins directory is an independent site with no official affiliation to DeepSeek or Huafang. When installing any third-party plugin, the source code is the standard of truth.

Conclusion¶

silverhand-dsh-pet solves a very small pain point: knowing what the agent is doing without staring at the window. It implements cleanly — two HTTP routes plus a client polling every 300ms, with a clear mapping from events to states. It is both a small toy and a DSH plugin sample that can be written as a reference.

Directory Page: https://www.skillhub.cn/plugins/Qiao-NEYC/silverhand-dsh-pet
GitHub: https://github.com/Qiao-NEYC/silverhand-dsh-pet

silverhand-dsh-pet: A desktop pet at the bottom-right corner of the DSH Web GUI that reacts to agent status.