Introduction¶

When an agent in DeepSeek Harness (DSH) runs long tasks, it usually uses todo_write to maintain a task list. This list sits in the conversation panel, with no hints, no progress display; you have to click it open yourself to know which step it’s on. dsh-todo-progress-hud lifts the same list above the input box, turning it into a persistent progress bar, where progress, the current step, and the status of each item are visible at all times. It is maintained by heisedexiaoniukou-max, MIT licensed, and belongs to the client-side plugin category.

Below is an introduction to the positioning, installation, and usage of this plugin.

Positioning and Data Source¶

The plugin does not generate any data; it only reads the session projection todos. Therefore, the content it displays is always consistent with the agent’s todo_write, requiring no extra configuration or synchronization logic, and involving no network requests or persistence. Sessions without a todo will not render any content.

It works by accessing the position directly above the input box, with the mount point being conversation.input.dock. It occupies the exact same slot as DSH’s built-in task panel, so it will not result in duplicate task information.

Core Features¶

1. A persistent task bar. The header is always visible; expanded, it shows the full list; clicking the whole bar toggles collapse/expand. The collapse state is saved in localStorage.

2. Real-time progress. The detailed progress bar transitions smoothly, the counter (e.g., 2/5) follows changes, and the current step rotates automatically.

3. Colored status. Completed turns green, in-progress is indigo with a soft glow, failed turns red, and pending is hollow.

4. Failures are visible. Nodes starting with ⚠ / ✗ / ❌ are marked as failed; the whole border warns, and progress won’t pretend to be normal.

5. Appearance follows the theme. It uses only --dsw-alias-* theme variables, has no shadows or overlays, and the width is aligned with the input box. Dark mode automatically switches to a brighter accent color and respects the system prefers-reduced-motion.

Environment Requirements¶

• DeepSeek Harness >= 0.2.0 (uses the conversation.input.dock slot)
• Only applicable to Web/Desktop pages; pure headless environments do not render

Installation¶

Install via GitHub, follow the default branch, and always get the latest version:

dsh plugin --profile web add github:heisedexiaoniukou-max/dsh-todo-progress-hud

To lock a version, add #v2.1.0 after the repository address:

dsh plugin --profile web add github:heisedexiaoniukou-max/dsh-todo-progress-hud#v2.1.0

Local directory installation (use for development/debugging):

dsh plugin --profile web add /absolute/path/to/dsh-todo-progress-hud

You can also install it via the DSH UI under Settings → Plugins, or let the agent call plugin_manager’s install_bundle. Refresh the page after installation to see the task bar.

Typical Usage¶

The agent calls todo_write normally, and the task bar appears, lighting up nodes in real-time. Below is the conventional syntax for node failure; failed nodes must start with ⚠️ in the content:

todo_write([
  { content: "K1 Locate Issue", status: "completed" },
  { content: "⚠️ K3 Debugging (API 500)", status: "in_progress" },
  { content: "K4 Regression", status: "pending" }
])

Behavior mapping:

Permissions and Side Effects¶

The plugin requires no tool permissions, network permissions, or Host service. The only persistence data is the collapse preference stored in localStorage. Additionally, todo-progress-hud:motion can be used to force animations on even when system motion is reduced.

The plugin runs with the permissions of the current dsh process. You should check the source code and license before installing to confirm it meets your environment requirements.

Implementation Details¶

The plugin consists of two halves: the Host half index.js and the Browser half client.js. client.js is the only real implementation; it is dependency-free, unbundled, has no build steps, and is registered via window.__ModuleLoader__.load({ id, factory }). Changes take effect after refreshing the page.

A detail worth mentioning: the host clears the projection on every turn/start. The plugin caches the last non-empty list per session to avoid task bar flickering when switching lines. Styles use only theme variables, and dimensions use em and --dsh-content-font-size for responsiveness.

You can confirm the version actually loaded by the browser by executing window.__TP_HUD in the console.

Uninstall¶

dsh plugin --profile web remove dsh-todo-progress-hud

Summary¶

It solves the same problem: the agent’s todo list is hidden in the conversation panel, requiring manual clicks to see progress on long tasks. Now this list is displayed directly above the input box, with progress and failed nodes visible at a glance. It is suitable for users running multi-step tasks in DSH Web/Desktop clients who don’t want to be interrupted by the task panel.

Directory: https://www.skillhub.cn/plugins/heisedexiaoniukou-max/dsh-todo-progress-hud

GitHub: https://github.com/heisedexiaoniukou-max/dsh-todo-progress-hud