Preface¶

When coding or running workflows in DeepSeek Harness (DSH), the built-in todo_write binding is confined to a single agent session: it replaces the entire table, uses three states, and the plan vanishes when the session ends. To maintain the same task list across multiple machines or workspaces, or to allow humans and agents to co-edit the same records, todo lists need to be persisted outside the conversation, accompanied by a clear set of handover and closure rules. Below is an introduction to the community plugin dsh-global-todo (maintainer LUgABeEEE), categorized as a workflow. It uses a single JSON file to host the list and supports step plans, session read-back, and manual confirmation of “completion.”

What is this¶

dsh-global-todo is a cross-session todo plugin for DSH: you and the agent read and write the same JSON file together. With one click, you can hand over a specific todo (including steps) to a new session or an existing bound conversation. When an agent declares completion, the entry enters a pending review state, requiring manual confirmation or rejection before it is considered truly closed.

Comparison with the built-in todo_write as described in the README:

The current package version is 0.12.13 (see repository package.json), licensed under MIT. The GitHub repository has approximately 3 stars and 2 forks (based on directory page clues).

Core Features¶

Single File JSON as the Entire List¶

The list is not buried in session logs. You can directly view, compare, commit to version control, or place it on a NAS or another machine.

Steps: Execution Plan within a Todo¶

A single todo supports a maximum of 20 steps, each with 200 characters (LIMITS defined in lib/model.js). Each step is { text, done }, representing checkable lines within the same work unit, not subtasks with independent IDs.

• Add row-by-row in the panel via “More fields → Steps”.
• Check steps in the details view; the list row displays e.g., steps 2/5.
• During Hand-off, the dispatched prompt lists step numbers, with completed items prefixed by [Done].
• Exports to Markdown as nested - [ ]; imports can read them back.

Evidence Sentence (Evidence)¶

evidence stores the original quote captured when creating the todo (up to 300 characters). global_todo_capture requests this from the model, and global_todo_add can write it; details are displayed in In the author’s words as a quote block. Manually created todos lack this field. Markdown exports include Original Quote:.

One-Click Handover and Four Modes¶

Handover is not about pasting large blocks of instructions: the plugin checks the working directory and passes the todo’s steps as a numbered plan to the target session. The details panel allows viewing the bound session status and opening the conversation.

Session Read-back¶

When a handover is advanced in a different conversation, you can see “what it just said” without switching windows. GET /api/global-todo/session?id= returns alive, dir, and the tail of the last assistant message (bounded: approx. 200 sessions in memory, 400 chars per tail, sourced from assistant/message; not persisted to disk, lost upon Host restart). No tail indicates the current process has not seen speech from that session yet.

Pending Review: “Done” is a Declaration, Not the End¶

After an agent calls global_todo_done (or the watcher triggers on a clean turn), the record becomes done with review: { pending: true }. The list displays Needs review, and the top bar shows a Review count.

Markdown Import and Export¶

JSON is the round-tripable authoritative format. Markdown facilitates human reading, diffing, and manual editing (manual edits to doing or cancelled in the list will become open upon import, as there is no “in progress” state).

Export example structure:

- [ ] Title
      Priority: High · Due: 2026-10-21T18:00 · Tags: Release, Docs
      Original Quote: ...
      Description: First line
      - [x] A step

• Export: More actions → Export Markdown, or GET /export?format=md (grouped: Incomplete / Completed / Archived).
• Import: More actions → Import (.md), or POST /import { markdown }; Markdown lacks IDs, so it will not overwrite existing records, always creating new ones.

Field labels are in Chinese (Priority / Due / Tags / Original Quote / Description / Attachments / #). Unparseable dates are discarded; lines without - [ ] will cause a rejection with a reason provided.

Weekly Report¶

More actions → This week (GET /report?days=7) derives “what was moved this week and whether it landed in files” based on completion records, without storing extra data. Fields include: finished, sessions, created, pendingReview, files (lists up to 12 paths, fileCount is the total). days greater than 90 is clamped to 90; missing or non-positive values default to 7 days.

Installation and Activation¶

Environment requirements (from README and package.json):

• DeepSeek Harness 0.2.x (engines.dsh is >=0.2.0-rc.1 <0.3.0, development and verification targeted 0.2.1-rc.2; Host version mismatch will skip this bundle).
• Node >=22.19.0.

Official installation command:

dsh plugin add dsh-global-todo

After installation, the global todo interface can be used in the DSH panel. The repository also provides a CLI: dsh-global-todo-doctor (npm run doctor / tools/doctor.mjs) for environment checks. For a shorter introduction, see the repository’s 5-minute quickstart and Chinese README.

Typical Usage (Reproducible Flow)¶

1. Install Plugin (see command above), ensure Host version is within the engines.dsh range.
2. Create or Capture Todo in Panel: Use the capture flow (global_todo_capture / global_todo_add) if original quote evidence is needed; fill in steps, due dates, tags, etc. in “More fields”.
3. Handover Execution: Select the handover method in details (reuse bound session or new session), agent proceeds by numbered steps; view Session read-back in details if necessary.
4. Agent Closure: Trigger global_todo_done upon completion; you Confirm done or Send back in Review.
5. Backup and Collaboration: cat, diff, and git commit the JSON file; use Export Markdown for readable summaries and Import to batch add from Markdown.

The panel also supports inbox confirmation, due reminders, multi-select status, etc.; baseline screenshots for each state are in the repository’s docs/screenshots/.

Use Cases and Notes¶

Who it is for: Those who need to share the same todo list across multiple DSH sessions and workspaces; those who want agents to execute planned steps with mandatory human confirmation for “completion”; those who want to put lists into git/NAS and Markdown workflows.

Permissions and Security: The plugin runs with the current dsh process permissions and can read/write the JSON and related APIs you configure. Please read the GitHub source code and the MIT license before installation, and assess whether it is suitable for production use yourself.

Ecosystem Note: The DSH community plugin catalog (e.g., the entry on SkillHub) is an independent site with no official affiliation with DeepSeek / High-Flyer; installation sources should adhere to the commands given in the README. Do not construct installation URLs that do not appear in the documentation yourself.

Conclusion¶

dsh-global-todo transforms todos from “temporary plans in a single session” into “a JSON file you own,” addressing common gaps in human-agent collaboration through step planning, one-click handover, session read-back, and pending review closure. To learn more, visit the plugin’s Catalog Page, Project Homepage, and GitHub Repository.