Introduction

In DeepSeek Harness (DSH), agents typically use the built-in todo_write tool to record task plans. The official UI renders the plan as a thin strip above the input box, but this thin strip is easy to miss and automatically collapses while the agent is working continuously, making progress invisible.

This raises a problem: when an agent runs for ten minutes without finishing, users often have to scroll through the conversation history to find out “How far along is it?” dsh-todo-float-ball moves this checklist into a persistent floating ball on the screen, resolving the progress visibility issue.

What Is This

This is a DeepSeek Harness (DSH) client plugin maintained by developer loyalchiiina. It transforms the agent’s task checklist into a persistent, draggable floating ball that displays completion progress and current task status in real time.

The plugin is licensed under MIT and does not upload data or perform telemetry.

Core Features

  • Persistent Floating Ball: The ball defaults to the bottom-right corner of the screen, supports dragging, saves its position to localStorage, and automatically restores that position after closing and restarting.
  • Real-Time Progress Display: The ball surface directly displays the done/total ratio and a ring progress bar, while the current in-progress task name is shown below.
  • Dual Data Synchronization: It monitors the official todo panel with a DOM observer and combines that with session projection frame parsing, ensuring the checklist remains complete even if the official panel is collapsed.
  • History Archive: When a new plan overwrites an old one, the old tasks do not disappear but are moved to a “History Archive” area.
  • Pinned Sessions: Multiple sessions can be pinned and displayed side by side in the panel, making it easier to monitor parallel work status.
  • Capsule Mode: Right-click the floating ball to switch to a capsule form that shows only the current task and count.
  • Skin System: Shares a catalog of 120+ skins with dsh-skill-browser and dsh-font-enhancer.
  • Discipline Injection: Enabled by default, it enforces that the first tool call in each conversation turn must be todo_write, preventing the agent from missing plan updates.

Typical Usage

  • Expand/Collapse: Click the floating ball to expand the full task panel. Click again or press Esc to collapse it.
  • Capsule Mode: Right-click the floating ball to switch to a capsule form that shows only the current task and progress.
  • Drag Positioning: Hold the ball and drag it to any location. The position is saved independently per configuration profile.
  • Status Recognition: Use the ball color to determine the status: orange pulsating indicates in progress, green indicates all complete, blue indicates pending only, and gray indicates no checklist.
  • History Management: In the panel’s history area, old tasks can be hidden, batch-cleaned, or restored with one click.
  • Layout Switching: The pinned session list can be switched between two layouts: “vertical stacking” and “horizontal side-by-side.”

Applicable Scenarios and Notes

  • Zero Intrusion: The plugin uses Shadow DOM and all:initial for style isolation. It does not modify the official panel, conversation, or other plugins, and it does not generate telemetry data.
  • Zero Configuration: It can be used immediately after installation, with no configuration file required.
  • Dual-Platform Support: The same codebase supports both the Electron desktop client and the Web client.
  • Discipline Injection Note: The plugin enables “Discipline Injection” by default, requiring the first tool call in every conversation turn to be todo_write. To disable it, explicitly set enforceFirstTodoWrite: false in the configuration. Only an explicit boolean false disables this feature.

Summary

dsh-todo-float-ball is a lightweight UI helper designed for long-running DSH task executions. It solves the pain point of progress tracking through a persistent floating ball and is suitable for developers who need to run agents for extended periods with minimal supervision.