English · Chinese
dsh-todo-list — a To Do List plugin for DeepSeek Harness (DSH)
A deployment-level DeepSeek Harness (DSH) To Do List plugin: it recognizes key items from conversations — natural chat, imported notifications, announcements, and email content — turns them into dated to-dos, and manages them from the To Do List entry in the left sidebar. The plugin mounts as a bundle into a profile (dsh plugin add one-click install) without modifying DSH source. No approval or configuration needed; data and the entry survive restarts.
Feature Overview
- Understand-notification skill: a packaged skill (
understand-notification, ships in skills/ and registers through a dedicated todo-skills provider) that teaches the model to extract actionable items from notifications, announcements, emails and conversations into a structured JSON — pure extraction rules, no tool calls inside the skill.
- Extract to-dos with preview & confirm: the model parses the text per the skill and calls
todo_preview to stage candidates; a multi-select popup appears, and items are written only after you confirm — nothing is added without your approval.
- Seven model tools:
todo_preview / todo_add / todo_list / todo_complete / todo_remove / todo_update / todo_today for staged-preview and direct CRUD inside a session.
- REST API:
/api/todo with list, batch-add, update, delete and clear-completed endpoints, plus /api/todo/pending (list / stage / clear) and POST /api/todo/pending/confirm for the preview-confirm flow.
- Sidebar panel: a To Do List entry plus Pending/Done tabs; click an item for details (due date, days left, urgency/importance, acceptance, notes). Both the detail popup and the preview popup are draggable by their headers.
- Settings page: language (Chinese / English), panel opacity and width, persisted automatically; the preview popup shares the same opacity setting.
- Reliable persistence: local JSON with atomic writes and legacy-data migration; nothing is lost on restart.
Installation
Prerequisites: a working DSH web profile (usually at $DSH_HOME/profiles/web, with DSH_HOME defaulting to ~/.dsh) and an available dsh command.
Recommended: dsh plugin add
dsh plugin --profile web add dsh-todo-list
This runs pnpm add dsh-todo-list inside the profile directory; because the package declares dsh.bundle.patch, dsh plugin automatically appends it to the profile's bundle layer (dsh.profile.bundles) — no manual edits to package.json or cordis.patch.yml. Restart dsh web after installing.
Alternative: local file: install
A file: install needs the project source (this repository), not the npm package — the npm tarball only ships the compiled lib/, the packaged skills/ and cordis.patch.yml, with no src/ or TypeScript toolchain to build from. Get the source first:
git clone https://github.com/perry-ai/dsh-todo-list.git # or download the zip from GitHub
Then build the output and declare the dependency:
# 1. Build the project in the source directory ($SRC)
cd "$SRC"
pnpm install # the prepare script compiles src/ → lib/
# 2. Declare the dependency: edit $PROFILE/package.json, add to dependencies
# "dsh-todo-list": "file:<path to $SRC>"
# 3. Join the composition: edit $PROFILE/cordis.patch.yml, append
# - insert:
# - id: dsh-todo-list
# name: 'dsh-todo-list'
# 4. Install and restart
cd "$PROFILE"
pnpm install
A file: dependency is installed by copy (not linked); pnpm may skip copying when it detects no content change — use pnpm install --force in that case. The plugin is ready after restarting dsh web.
Quick Start
Add to-dos directly in a DSH conversation using natural language, e.g.:
Please note two items for me: send the draft quarterly business analysis report to management by August 26 — it's important; also submit last month's expense claim in early September, no rush.
The model automatically calls todo_add, parsing the text into to-dos (title / due date / urgency / importance / acceptance), e.g.:
Added 2 to-dos:
[ ] 2026-08-26 Draft the quarterly business analysis report and send it to management (urgent, important, top priority) (7 day(s) left) — important
[ ] 2026-09-01 Submit last month's expense claim (13 day(s) left)
Now: 2 pending, 0 done
Note: model tool output is currently rendered in Chinese; the English above is an illustration.
Then you can:
- call
todo_today so the model converts relative dates ("tomorrow", "next Monday", "end of month") into concrete dates;
- use
todo_list to view the list, and todo_complete / todo_remove / todo_update to maintain it (title, due date, urgency, importance, acceptance, notes, etc.);
- or open the To Do List entry in the left sidebar: switch between Pending/Done, click an item for details (due date, days left, urgency/importance, acceptance, notes), and open settings to switch the language or adjust opacity/width;
- or use the REST API directly:
GET http://127.0.0.1:3080/api/todo to list, POST /api/todo to batch-add.
Storage & migration
- The list lives at
$DSH_HOME/storages/dsh-todo-list/todos.json with the shape { version, todos, nextId }.
- Every change first writes
<file>.tmp and then atomically renames it, avoiding half-written files.
- On first load, if the legacy
<cwd>/todos.json from the old dynamic plugin exists, it is migrated to the new location; the original file is kept.
- Reads go through an in-memory snapshot that is refreshed after every write.
Features
- Model tools: the Host registers 7 global tools —
todo_preview / todo_add / todo_list / todo_complete / todo_remove / todo_update / todo_today. todo_add turns multiple items from a piece of text into to-dos in one call, each with a YYYY-MM-DD due date; todo_preview stages the parsed candidates for the confirm popup instead of writing them directly.
- Understand-notification skill: the packaged
understand-notification skill defines the extraction rules (identify actionable items, resolve due dates — explicit or relative to the current date, judge urgency/importance, acceptance criteria, notes) and the exact JSON output shape; it carries no tool-call instructions — the bridge to todo_preview lives in the tool description. The skill is discovered from the package's skills/ directory via the todo-skills provider (independent of the host filesystem provider).
- Fields & priority: every to-do carries a title, due date, urgency, importance, acceptance criteria and notes. The priority is derived automatically from urgency + importance — both high → urgent, shown as the badge URG in the list, either high → high, both medium → medium, either low → low.
- REST API:
GET /api/todo (list), POST /api/todo (batch add), PATCH /api/todo/:id (update), DELETE /api/todo/:id (delete), POST /api/todo/clear-completed (clear completed); preview flow: GET/POST/DELETE /api/todo/pending (list / stage / clear candidates) and POST /api/todo/pending/confirm (write the checked candidates).
- Sidebar entry: a To Do List entry at the bottom of the sidebar — icon + label + pending-count badge in the wide bar, a round icon when collapsed to a rail. Clicking opens a panel with Pending/Done tabs; the pending tab shows a pending-count badge.
- Detail popup: click any row to float a detail popup to the right of the panel — due date, days left, color-coded urgency/importance, acceptance criteria and notes; the clicked row is highlighted. The popup is draggable by its header.
- Preview-confirm popup: when the model calls
todo_preview, a popup (registered in the shell.overlay slot) shows the candidates with multi-select checkboxes; confirming writes the checked items via /api/todo/pending/confirm, cancelling clears them. Its visual language — background, opacity, rows, colors — matches the detail popup exactly, so both look identical side by side. Draggable by its header too.
Architecture
src/index.ts mounts the /api/todo prefix routes through the webServer service, registers the 7 model tools through the optional tools service, and registers the packaged-skill provider through the optional skills service.src/skill-provider.ts scans the packaged skills/ directory (<name>/SKILL.md or <name>.md), parses minimal frontmatter (name / description / whenToUse), and exposes them as a filesystem-style skill provider — zero extra runtime dependencies, and no conflict with the host filesystem provider (unique provider name todo-skills, scans only its own directory).src/types.ts declares domain types and shared constants; src/services.ts declares the structured subset contracts (types only, zero runtime) of the DSH/Cordis services this plugin consumes.src/store.ts handles persistence: in-memory snapshot + atomic rename writes, migrating old dynamic-plugin data on first load.src/domain.ts centralizes validation (title, date format), days-left math, priority derivation (derivePriority), item projection and CRUD, plus candidate staging for the preview flow (stageCandidates / pendingSnapshot / confirmPending / clearPending).src/api.ts dispatches REST routes; request bodies are JSON, capped at 1 MiB (413 when exceeded, 400 for invalid JSON). Besides CRUD it serves /api/todo/pending (GET list / POST stage / DELETE clear) and POST /api/todo/pending/confirm.src/tools.ts defines the JSON Schemas and text rendering of the 7 todo_* tools (todo_preview stages candidates without writing).src/client.ts is the browser half: it self-registers as a single file via window.__ModuleLoader__, injects styles, and mounts the sidebar entry, detail popup, settings page and the preview-confirm popup (registered in the shell.overlay slot), reading and mutating data through /api/todo. The detail and preview popups share the same opacity setting and are draggable by their headers.
Build
Requires Node 22.19+ / 24+ (same as DSH) and the TypeScript toolchain:
pnpm install # installs devDependencies and triggers the prepare build into lib/
pnpm build # manual build: tsc -p tsconfig.json, src → lib
pnpm typecheck # type-check only: tsc --noEmit
lib/ is build output and is not committed (see .gitignore); pnpm install regenerates it from src/ via the prepare script, so run pnpm install once in this project before a file: install. The published package ships .d.ts declarations, so TypeScript consumers get types out of the box.
Manual verification
- Mount the plugin and restart
dsh web; confirm the To Do List entry appears at the bottom of the sidebar.
- In a session, call
todo_today to get today's date, then todo_add to batch-add items.
- Call
todo_list; confirm every item returns a title, due date and days left.
- Open the sidebar panel and switch between Pending/Done; confirm the pending-count badge and that completed items show no due badge.
- Click an item to open the detail popup; confirm due date, days left, color-coded urgency/importance, acceptance criteria and notes; the clicked row is highlighted.
- Open the settings page and adjust opacity and width; confirm changes apply immediately and persist.
- Request
GET /api/todo and confirm {"todos":[...]}; PATCH an item as done, list again, and confirm the done state and pending count change.
- Restart the Harness and confirm the to-dos are still there.
Known limitations
- No cross-process file lock: with several Hosts running against the same
$DSH_HOME, each process keeps its own in-memory snapshot and writes may overwrite each other.
- To-dos are not shown inside the conversation; they are managed only via the sidebar entry and the
todo_* tools.
- Priority cannot be set manually; it is always derived from urgency and importance.
- The sidebar footer fix depends on the CSS class
[class*="footerActions"]; renaming it in the platform would break the layout.
- Relative dates (tomorrow / next Monday, etc.) are converted to concrete dates only after the model calls
todo_today first.
- Preview candidates are held in memory: they are discarded on a process restart, and a new
todo_preview call replaces the whole pending set. Nothing is written until you confirm in the popup.
