Introduction

DeepSeek Harness (DSH) uses a pluggable architecture. When developing or debugging agents, you often need to minimize the Web UI or keep the browser in the background, making it hard to intuitively perceive the Agent’s runtime status (such as whether it is thinking, waiting for approval, or has finished). MoodBall is designed to solve this problem by freeing Agent status from the Web UI and floating it anywhere on the desktop.

What Is This

This is a macOS desktop pet plugin maintained by sundusk. It lets Agent status fly out of the Web UI and float anywhere on the desktop, providing a persistent Menu Bar item and an always-on-top desktop pet.

Core Features

The plugin includes the following core capabilities:
1. Persistent Menu Bar Item: Displays the current connection status, status name, and bridging method in the Menu Bar.
2. Always-on-Top Desktop Pet: The ball floats above all windows and can be dragged to any position (the position is saved automatically).
3. Multiple Skins: Provides Mood Ball and Rain skins that change in real time with Agent status.
4. Status Bubbles: Shows a comic-style bubble when not idle and hides it automatically when idle.
5. Real-time Status Bridging: Compatible with HTTP/status Socket interfaces, provides a user-level command Socket, and bridges status and input.

Installation and Enablement

Before installing, ensure your environment meets the following requirements:
* System: macOS 14+
* Dependency: DeepSeek Harness (DSH) is running
* Runtime: NPM/NPX versions require Node.js; the source version must be run from the source root directory with pnpm dsh

The installation command is as follows:

curl -fsSL https://github.com/sundusk/dsh-moodball/raw/refs/heads/main/install.sh | bash

Note: If you download and install from a Release, the plugin is not installed automatically. In that case, add the plugin manually in DSH.

Typical Usage

  1. Move Position: Grab the ball from any part and drag it; the position is remembered automatically.
  2. Interaction Feedback: Double-clicking the ball makes it shake left and right for about 2 seconds to indicate excitement; moving the mouse near the short horizontal bar below the pet turns it into a note button.
  3. Keyboard Shortcut: The default shortcut is Option+Space.
  4. Input and Screenshot: Paste a clipboard image directly into the input box, or click the paperclip menu to choose an area-selection screenshot.

Applicable Scenarios and Notes

  • Runtime Environment: The plugin runs with the permissions of the current DSH process. If you use the source version, you must run pnpm dsh from the source root directory.
  • Configuration Location: All configuration is completed in the MoodBall.app settings panel; the plugin itself has no settings (so no configuration card is displayed).
  • Interface Limitations: The MoodBall status Socket is read-only; input functionality is provided by a separate user-level command Socket.

Short Wrap-Up

MoodBall projects Agent status to the desktop in real time. With interactions such as dragging and double-clicking, plus status bubbles, developers can manage task progress without opening a browser. Configuration is centralized, maintenance is simple, and it is suitable for scenarios that require monitoring Agent status in the background.

Plugin Catalog
GitHub Repository