dsh-ai-ball: Adding a Floating Ball to an AI Agent via Files

Introduction¶

In the ecosystem of DeepSeek Harness (DSH), when developing agents, an Agent’s output is usually manifest only as log text. To give the Agent more intuitive feedback, such as a visual persona that can speak and express emotions, a middle layer is required. ai-ball is a floating-ball utility for Windows, and it controls its own behavior by reading specific files. The dsh-ai-ball plugin is the bridge that connects a DSH Agent with ai-ball; it is responsible for writing files, allowing the ball to “speak” or change state.

What Is This¶

dsh-ai-ball is a lightweight client plugin maintained by user Hyfwdnmd666. Its core responsibility is not to manipulate windows or launch processes, but to act as a “writer” by writing an Agent’s instructions into the log file that ai-ball is monitoring. This design allows any process, including non-DSH Python scripts, to act as the ball’s “brain”.

Installation and Enablement¶

Use the DeepSeek Harness command-line tool to install it. The plugin itself does not include the main ai-ball component, so it must be installed and running separately first.

dsh plugin --profile web add link:/path/to/dsh-ai-ball

Configuration¶

The plugin is configured in cordis.patch.yml. To ensure accuracy, ballDir (the directory where the ball component is located) is required, has no default value, and must be specified manually; otherwise, the plugin cannot write files.

- id: dsh-ai-ball
  name: dsh-ai-ball
  config:
    ballDir: C:\tools\ai-ball        # Required: directory containing ball.py for ai-ball
    startCommand: C:\tools\ai-ball\start.bat   # Optional: start command used by ball_launch
    cps: 50                          # Optional: typing speed
    heartbeatMs: 3000                # Optional: heartbeat interval, must be smaller than stale_s in the ball configuration
    files:                           # Optional: align with the ball's own config.json
      monologue: monologue.log
      input: input.log
      status: status.json

Core Features¶

The plugin provides six tool functions for controlling the ball’s behavior:

• ball_say(text, options): Speak. Writes the content to monologue.log, and the ball reads it out character by character. Supports the clear: true parameter to clear the screen before speaking.
• ball_mood(mood): Change expression. Supports states such as idle, thinking, nervous, smug, and broken.
• ball_panel(show): Show or collapse the monologue panel.
• ball_listen(): Read newly added input content from input.log.
• ball_status(): Report the connection status, including file size, last content, heartbeat status, and so on.
• ball_launch(): Launch the ai-ball process according to the configured startCommand.

Technical Details and Notes¶

1. Heartbeat Mechanism¶

The plugin continuously sends heartbeats (writes to status.json) to prevent the ball from being rendered gray due to timeout. If the heartbeat is not maintained, the ball’s brain state will become invalid.
* When ball_mood is called for the first time, the plugin starts a background heartbeat.
* When the plugin is unloaded/reloaded, the heartbeat stops automatically.

2. Panel Control Mechanism¶

ball_panel uses a sequence-number mechanism to avoid conflicts with the ball’s own logic. The panel field in status.json is a command rather than a state, while panel_seq is the sequence number. The ball executes the operation only once when the sequence number changes. This design prevents frequent plugin writes from causing the panel to flicker or seize control.

3. Input Monitoring and Encoding¶

ball_listen uses a byte cursor to read input.log, and it advances only up to the newline character. This is done to prevent decoding errors when reading in the middle of a UTF-8 character, which could cause permanent loss of content.

4. What It Does Not Do¶

• Does not check window state: The plugin only checks the file status, not whether the ball is running.
• Does not limit the number of instances: Repeated calls to ball_launch will create multiple ball instances.
• Does not render Markdown: The ball is the “mouth,” not a document, and it does not render Markdown formatting.

Summary¶

dsh-ai-ball is a thin plugin designed to solve the problem of visual feedback for Agents. Through file IO, it decouples DSH logic from the rendering layer of ai-ball. Correctly configuring ballDir and understanding the mechanisms of the heartbeat and panel sequence number are key to using this plugin well.

Plugin Directory Page
GitHub Repository