The plugin ecosystem of DeepSeek Harness (DSH) supports developers in extending the functionality of the Web interface through plugins. When operating an agent in the Web interface, the agent’s internal state (such as thinking, searching, and running commands) is often difficult to perceive intuitively. dsh-pet-in-frame is a plugin that floats a desktop pet in a corner of the Web GUI and follows the agent’s state by switching poses.

It is a single-package plugin maintained by HarmlessFunny. It maps the agent’s lifecycle states to visual animations or still images, addressing the issue that the Web interface provides abstract feedback and that tool-call progress is difficult to monitor in real time.

Core Features

The plugin listens to the agent’s lifecycle events to control the pet’s pose.

  • State response: The pet switches poses according to the agent’s current action, including think (thinking), search (searching), learn (learning), read (reading), bash (command line), edit (editing), plan (planning), ask (asking), subagent (sub-agent), cordis (service call), permission (permission), error (error), idle (idle), and sleep (sleeping).
  • Sub-agent isolation and indicator: Only the main agent’s activity drives the pet’s pose. When a sub-agent is running, a badge indicator is displayed inside the pet image. Tool-call or error events from sub-agents do not affect the main agent’s state.
  • Command badge: When the main agent runs a foreground bash or pwsh tool, the pet switches to the command pose and displays the corresponding badge fixed inside the image (such as bash_comp or pwsh_comp).
  • Background job tracking: It supports job tracking for background bash or pwsh commands. When a command succeeds, fails, or exits, the pet updates its display based on the state.
  • Interaction and performance: The client polls the state every 250 milliseconds, and pose-switching latency is about 0.25 seconds. It supports dragging (with viewport limits), hover scaling (100-320px), clicking to view a bubble, and hiding and restoring. It supports hot reloading; changes to images or manifest.json take effect within about 3-4 seconds.
  • No build steps: It is implemented in pure JavaScript and requires no additional build configuration.

Installation and Enablement

Before installation, ensure that the dsh web profile is already running and that pnpm is available on the system.

Installation command:

dsh plugin --profile web add dsh-pet-in-frame

After installation completes, the dsh web process must be restarted before the new plugin entry is loaded. The plugin’s cordis.patch.yml automatically inserts the loading line, so there is no need to manually edit cordis.yml.

Configuration and Use

Asset Directory Configuration

Image assets are located by default in the assets/ directory of the plugin package. Another path can also be specified through the DSH_PET_ASSETS environment variable or the loader’s config.assetsDir.

Convention Mode (Zero Configuration)

Place image files in the assets/ directory, and the filenames must match the action names (extensions: png/jpg/jpeg/gif/webp/svg).

assets/
├── default.png   # 空闲时的默认姿态
├── think.png     # 思考状态
├── search.png    # 搜索或阅读状态
├── bash.png      # 命令执行状态（可选）

Manifest Configuration (Explicit Control)

If more fine-grained control or frame animation is needed, create a manifest.json:

{
  "default": "default.png",
  "think": { "imgs": ["think1.png", "think2.png"], "delay": 1000 },
  "sleep": { "imgs": ["sleep1.png", "sleep2.png"], "delay": 500 },
  "bash": "bash.png"
}

Notes

  • Background job tracking: To support job tracking for background commands, the loader must implement the ctx.jobs.onJobDone interface.
  • Permissions: The plugin runs with the permissions of the current dsh process. Please check the source code and license (MIT) before use.
  • Sub-agent behavior: Shell invocations inside a sub-agent do not trigger the command badge; only the main agent’s tool calls drive the pet’s pose.

Summary

dsh-pet-in-frame provides intuitive agent-state feedback for DSH’s Web interface using simple still images or frame animations. It lowers the barrier to use through convention over configuration, while supporting hot reloading and rich interactions. It is suitable for scenarios that require real-time monitoring of agent behavior during development.