Introduction¶

Letting agents work in a repository has a common annoyance: all changes land in the same workspace. The changes from the previous task have not yet been committed, while the next task has already started, causing uncommitted content to get mixed together. If you want to use branch switching for isolation, you first have to deal with the current state.

Native Git worktree allows the same repository to maintain multiple checkouts at the same time, with each checkout attached to its own branch. What dsh-task-worktree does is integrate this capability into DeepSeek Harness (referred to hereinafter as DSH)’s session model: each task gets an isolated checkout, the main workspace remains untouched, and delivery and cleanup actions are executed by humans.

This article introduces its positioning, features, and usage.

What It Is¶

dsh-task-worktree is a community plugin maintained by Letter2025, licensed under MIT. Its one-sentence positioning is: Complete Git worktree support for DeepSeek Harness—providing an isolated git worktree checkout and a persistent manifest for each task.

Under DSH’s “everything is a plugin” architecture, it provides three things:

Each task gets an independent git worktree checkout, with branch names automatically prefixed by worktree/ (slashes are allowed);
Checkouts are recorded per repository in the manifest, and state persists across sessions and restarts;
Delivery and cleanup operations (merge back to the main branch, commit, delete) are restricted to humans and are not accessible to the model.

Core Features¶

An Independent Checkout per Task¶

Each time a task worktree is created, the plugin performs an independent checkout under <repo>/.dsh-worktrees/ and automatically creates a branch prefixed with worktree/. The main workspace is left completely untouched.

A session using worktree displays a branch badge in the session header and does not create workspace entries.

Persistent Manifest¶

All worktrees are recorded by repository in the manifest. Writes are performed as atomic operations (tmp + rename), and state persists across sessions and restarts. /worktree prune is responsible for cleaning up records whose checkout no longer exists and removing expired workspace registrations.

Division Between Model Tools and Human Commands¶

On the model side, three tools are available:

worktree_create: Create a task worktree; includeUncommitted can be used to bring uncommitted changes from the main workspace along as well;
worktree_list: List worktrees managed by the repository;
worktree_status: Check status.

Human commands cover the full workflow:

/worktree mode-on                        # 开启 worktree 模式
/worktree mode-off                       # 关闭 worktree 模式
/worktree create <name> --carry          # 手动创建，--carry 带入未提交更改
/worktree list                           # 列出
/worktree status                         # 查看状态
/worktree finish worktree/<name> <msg>   # 在 worktree 分支上提交并保留
/worktree bring-back worktree/<name>     # 将分支合并回主分支
/worktree remove worktree/<name> --force # 删除 worktree 与分支
/worktree prune                          # 清理失效记录

Among these, the three delivery and cleanup operations finish / bring-back / remove are restricted to humans and are not accessible to the model.

Installation¶

Requirements: the DeepSeek Harness 0.1.0-rc.7 package line, Git 2.31+, and Node 20+. Once satisfied, run:

dsh plugin --profile web add dsh-task-worktree

The plugin’s @deepseek-ai/* dependencies are only peerDependencies, provided by the host. The plugin does not install infrastructure copies into the profile.

Typical Usage¶

Enable Worktree Mode¶

There are two ways.

First: In an empty session, select “Worktree mode” from the dock dropdown (optionally enter a branch name; the worktree/ prefix is added automatically), then send the first message to trigger the model to call worktree_create.

Second: Do not select the mode, and directly ask the agent to execute:

用 worktree 隔离干活，任务叫 xxx

Additionally, /worktree mode-on and /worktree mode-off are used to manually enable or disable this mode.

Wrapping Up¶

After the steps above, the task is already running on an independent checkout and branch. When wrapping up, choose as needed:

/worktree bring-back worktree/<name>      # 将分支合并回主分支（要求主工作区干净）
/worktree finish worktree/<name> <msg>    # 在 worktree 分支上提交并保留
/worktree remove worktree/<name> --force  # 删除 worktree 与分支（--force 同时删除未提交更改）

Check and Cleanup¶

/worktree list
/worktree status
/worktree prune

prune cleans up records whose checkout no longer exists and removes expired workspace registrations.

Security Design¶

Delivery and cleanup operations (finish / bring-back / remove) are restricted to humans and are not accessible to the model;
bring-back requires the main workspace to be clean (MAIN_DIRTY) and refuses to run inside a worktree;
remove refuses to delete the worktree that the current session is working on (IN_USE);
All git operations are executed through ctx.subprocess (managed by the harness);
Manifest writes are atomic operations (tmp + rename).

Local Development¶

If you want to participate in development, the repository provides two entry points:

npm test              # 冒烟测试
npm pack --dry-run    # 发布前检查 tarball

Applicable Scenarios and Notes¶

Suitable scenarios:

Multiple tasks are advancing in parallel, and you do not want uncommitted changes to interfere with each other;
You want state to persist after a task is interrupted, so it can still be looked up after switching sessions or restarting;
You want operations such as merge and delete to be manually confirmed by humans instead of delegated to the model.

Notes:

The plugin runs with the permissions of the current dsh process; you should review the source code and license before installation (this project is MIT);
Version requirements: DeepSeek Harness 0.1.0-rc.7 package line, Git 2.31+, Node 20+.

Summary¶

dsh-task-worktree moves the task-level isolation workflow of git worktree into DSH: the model handles creation and work, delivery and cleanup remain in human hands, and state persists across sessions. If you often run multiple tasks in parallel in the same repository, you can try the steps above.

Community directory page: https://www.skillhub.cn/plugins/Letter2025/dsh-task-worktree
GitHub repository: https://github.com/Letter2025/dsh-task-worktree

It should be noted that skillhub.cn is an independent community directory site and has no official affiliation with DeepSeek / High-Flyer.

dsh-task-worktree: Isolated git worktree checkouts for each task