Foreword¶

When building agent applications, to-do tools answer the question: “What’s left to do?” What users truly care about is often another question: How long did this task take from creation to completion? dsh-todo-time-log merges tasks and time tracking into a single thing: managing tasks while automatically recording creation time and completion time, then presenting real duration using four views: table, kanban, gantt chart, and calendar.

Below is an introduction to this plugin. It is a DeepSeek Harness (DSH) plugin maintained by FantasyStarry, categorized as Workflow, licensed under MIT, and the npm package name is dsh-todo-time-log. Existing to-do solutions often stay at the checklist level; either they only have time fields but lack view organization, or they have complete views but do not record the completion moment. It connects “bookkeeping” and “reviewing accounts,” storing data in a local JSON file, offline, without uploading.

I. Core Capabilities¶

Time recording is a default behavior, not a configuration item. Every task writes the creation moment (local time YYYY-MM-DD HH:mm:ss). When completed, it automatically writes the completion moment; uncompleted tasks display -. Repeated completion or repeated cancellation will give clear prompts. The “Completion Time” column in the table directly provides two rows: “Duration / In Progress”; uncompleted entries also display elapsed time and an “In Progress” marker.

The four views share the same data card. Switching views preserves current filtering and sorting, with sorting unified by table headers:

• Table: The two columns of Creation Time and Completion Time are the protagonists.
• Kanban: Columns are divided by status. Cards carry priority, type, and duration. Supports grouping by status, category, or status × category lanes; lanes can be collapsed, and new items can be created within them.
• Gantt Chart: One bar = Creation → Completion. Uncompleted items extend to “Now”. Supports grouping by category, and can switch between All / Last 7 Days / Last 30 Days. The Gantt chart is calculated purely on the frontend, without new API endpoints.
• Calendar: Drops into cells based on creation or completion time. Clicking a day processes all entries for that day.

Each task can also carry a category, priority (High / Medium / Low), and type (Bug / New Feature / Improvement / Question / Misc / Other). When associating code files with @workspace_file, if no explicit category is provided, the directory where the file is located is automatically taken as the category.

II. Four Entry Points¶

The four entry points—panel form, conversational one-liner, /todo slash command, and agent tool todo_time_log—share the same set of parsing rules (parseQuickAdd() in lib/parse.js), avoiding drift between the two sides’ rules.

The markup syntax is universal across three places:

New task write weekly report #Work @src/auth/login.ts
Fix login bug #Work !high ^bug
Buy milk @Life; reply to email [Work]
Project: Study organize notes, finish chapter 3

• Category: #Work / @Life / [Work] / Project:Work / Category:Work. Takes the leftmost non-empty value and strips it from the title.
• Priority: !high / !medium / !low. Also accepts !h !m !l and Chinese equivalents !高 !中 !低. If not specified, it falls back to the form selector.
• Type: ^bug / ^feature / ^improvement / ^question / ^chore / ^other. Supports Chinese and type:bug / type:bug; unknown values are kept as-is.
• File: @path/file or @"docs/My File.md". Recorded as a workspace-relative path.
• Multiple items: Separated by newlines, ；, or ;. Only lines with content are skipped; empty to-dos are not created.

The agent tool is attached to todo_time_log, supporting list / get / create / complete / uncomplete / update / delete / health, sharing the same implementation as the UI:

todo_time_log { "action": "create", "title": "Fix login", "priority": "high", "type": "bug" }
todo_time_log { "action": "list", "filter": "pending", "sortBy": "priority", "direction": "asc" }
todo_time_log { "action": "complete", "id": "ttl_…" }

The data file path is <DSH_PROFILE_DIR or ~/.dsh>/todo-time-log/todos.json. It uses temporary file + atomic rename for replacement, serialized writing, and cross-process file locks for protection. On file corruption, it automatically backs up and rebuilds. The “Data” menu in the header provides lossless JSON backup and CSV export (for Excel statistics); import previews before writing and supports merge / add-only / overwrite all, with automatic backup and direct undo capability. Panel shortcuts: / focuses search, n focuses new, f cycles through filters.

III. Installation & Activation¶

Requirements: DeepSeek Harness >= 0.2.0-rc.2 < 0.2.3-0 (declared in engines.dsh, verified on real device in 0.2.2-rc.1), Node.js ≥ 20.

Install the bundle in the Plugin Manager, entering dsh-todo-time-log as the package name. Alternatively, have the agent of the current session execute the installation:

plugin_manager action=install_bundle target=dsh-todo-time-log

Installation executes package installation (pnpm), writes the Host lines declared in dsh.bundle.patch, and enables the bundle. It only takes effect if the return is application: "applied". The Host side requires closing and reopening the plugin (or restarting the desktop app) to load new modules; the Client side (dsh.client.immediately) loads on the next page refresh. After successful installation, an entry for “To-Do Time Log” appears on the left navigation, and the Plugin Manager displays the Chinese name, description, and icon.

For local development, install using the link method, changing target to the local repository’s absolute path. After modifying lib/*.js, you also need to close and reopen the plugin (or restart the desktop app) to load the new Host module, while UI changes just require refreshing the page. To uninstall:

plugin_manager action=remove_bundle target=dsh-todo-time-log

After uninstalling, the data file is retained; manually delete todos.json to clear it.

There are two external ways to configure the data file path. The current build does not export the Config schema, and the plugin details page has no configuration form, so only these two methods are available:

# cordis.patch.yml line configuration (highest priority), writes plugin's config
config: { dataFile: 'D:/data/todos.json' }

# Environment variable DSH_TODO_TIME_LOG_DATA (lower priority)
export DSH_TODO_TIME_LOG_DATA=D:\data\todos.json

When neither is set, the default path is used. Relative paths are resolved relative to the config directory. See the repository’s docs/limitations.md for specific reasons for limitations.

IV. Typical Usage¶

1. Write the title in the top input box of the panel, conveniently tagging #Work for category and @lib/store.js for referencing workspace files; categories, priorities, and types can be selected directly. Press Enter or click “Add”. When tagged, the Host parses it uniformly, and the title will not retain #Category / @File.
2. Click the checkbox at the start of the row (the checkbox on the card in Kanban) to complete the task. The completion time is automatically written, and a toast pops up at the bottom; “Undo” allows one-click return to the uncompleted state, and the “Completion Time” column immediately appears with a time.
3. When you need to record multiple items at once, click “Batch” to the right of the new item box to enter conversational entry. First confirm the workspace (file completion with @ is isolated by workspace), write multiple items in one sentence, and send. After sending, you get receipts one by one; if unsatisfied, you can undo the entire batch.
4. If you don’t want to leave the conversation flow, use the slash command. Write in the Harness main input box:

/todo write weekly report #Work lib/store.js

5. When you want the model to record or query on your behalf, call the agent tool todo_time_log. Parameters are the same as the panel form, with action covering CRUD and health checks.

V. Use Cases & Notes¶

Suitable for those who use DSH as a workstation and want their to-do list to also be a time log, especially scenarios requiring an agent to record to-dos based on rules, followed by reviewing time using Gantt charts or calendars.

A few points need attention. Before installation, check the source code and license (the repo is MIT, LICENSE is in the root directory), and run the plugin with the current DSH process permissions. It is not a standalone app; a working DeepSeek Harness must exist first, and the version must satisfy the engines.dsh constraints. The plugin details page currently has no configuration form, so the data file path must be specified via cordis.patch.yml or environment variables. All data is local, offline, and not uploaded.

VI. Summary¶

The value of this plugin lies in merging the “To-Do List” and “Time Ledger” into one interface: multiple entry points are not fragmented, the four views share one set of parsing and data, completing an action is bookkeeping, and undo and import/export are included. If you are a DSH user and your to-dos happen to need to answer “How long did it take,” you can start here.

• Directory: https://www.skillhub.cn/plugins/FantasyStarry/dsh-todo-time-log
• GitHub: https://github.com/FantasyStarry/dsh-todo-time-log
• npm: https://www.npmjs.com/package/dsh-todo-time-log