Introduction

When running tasks in DSH, you often need to switch back to the main interface to check the status. For long-running tasks or when the process is stuck at the authorization step, this switching is very costly. DSH macOS Pet solves this problem: it is a macOS desktop pet that floats above all windows and displays the Agent’s status in real time.

It does not require switching windows and does not occupy any space on the DSH page. You only need to glance at the corner of the screen to know whether the current Agent is working, waiting for authorization, or has already finished.

Install and Enable

Before installing, ensure that your environment already has DSH configured. Use the following command to install the plugin:

dsh plugin --profile web add dsh-macos-pet

After installation, start the DSH Web page and you can see the desktop pet floating above the desktop:

dsh web

If you are upgrading from an older version, specify @latest:

dsh plugin --profile web add dsh-macos-pet@latest

If you do not want to install DSH and only want to run this program standalone, you can directly clone the repository and run ./bin/dsh-macos-pet.

Features

This plugin displays the Agent’s status in a native macOS window that overlays all windows.

Status Monitoring

The pet automatically follows status changes from the local DSH instance, with no additional configuration required. It mainly includes the following states:

  • Idle: It has nothing to do, breathing and occasionally blinking.
  • Working: DSH is executing a task.
  • Waiting for You: Stuck at a confirmation or authorization step.
  • Error: The task execution failed.
  • Happy: It just finished a round and automatically returns to Idle after 3.2 seconds.
  • Sleeping: It dozes only when the Agent is idle and the mouse is not moving; any movement or tapping it will wake it up.

Skin System

The plugin ships with seven built-in skins: Deep Whale, Blue Whale, Wirecore, Nautilus, Jellyfish, Claude, and Star. Each skin includes six states, and each state has three animation frames.

In addition, the plugin supports DIY skin generation from a single image. Using the skill built into the plugin, the Agent can expand one image into the eighteen poses required for a complete skin. Generated skins are saved under the ~/.dsh-macos-pet/skins/ directory and will not be lost when the plugin is upgraded.

Common Operations

You can control the pet through the right-click context menu or command-line arguments.

Adjust Size

Adjust the pet’s display size:

./bin/dsh-macos-pet --scale 0.5

(The default size is 0.7)

Specify Skin

Specify the skin to use at startup:

./bin/dsh-macos-pet --skin jellyfish

Generate a Skin Preview Image

After creating a skin, you can use the following command to combine the six states into a single image for preview:

./bin/dsh-macos-pet --skin-sheet <你的皮肤id>

Other Operations

  • Reset Settings: ./bin/dsh-macos-pet --reset
  • Stop the Pet: ./bin/dsh-macos-pet --stop
  • Run in Foreground: ./bin/dsh-macos-pet --foreground (logs are output to the current terminal)

Notes

Before using it, please note the following:

  • System Limitation: macOS only. Windows and Linux are untested.
  • Interaction Logic: The pet has a transparent margin around its edges; clicking this area does not pass through to the window behind it.
  • Missing Features: The current version lacks a settings window and a docked mini mode.
  • Generation Progress: Skin generation does not display a progress bar; you can only check progress through the Agent’s output.
  • Zero Dependencies: The plugin has no third-party dependencies and runs using the Python bundled with the system.

References