dsh-task-worktree
Complete Git worktree support for DeepSeek Harness.
A community plugin that gives DSH the task-scoped worktree workflow of Qoder / Codex / Claude Code: each task gets its own isolated git worktree checkout on its own branch, recorded in a per-repo manifest so it survives sessions and restarts. The main workspace stays untouched; conversations that use a worktree are marked with a branch badge on the session header (no workspace entry is created), and the changes can be brought back (Move to local) or committed directly on the worktree branch — always under explicit human control.
It follows the design of Qoder's Worktree execution environment, Codex's codex worktree create --permanent, and Claude Code's --worktree sessions, adapted to DSH's session/workspace model.
Design
| Concept (this plugin) | Qoder | Codex | Claude Code |
|---|
| Task-scoped isolated checkout | Worktree execution environment | codex worktree create --permanent | claude --worktree <name> |
Worktrees live in <repo>/.dsh-worktrees/ | background worktree checkout | .codex/worktrees/ | .claude/worktrees/ |
| Durable registry survives restarts | per-session | global index | session binding |
| Own branch per task | branch selector | — | worktree-<name> |
| Open as a DSH workspace from the GUI | panel selector | codex worktree open | launches into the worktree |
| Mark the conversation using the worktree | session badge | — | — |
| Bring changes back to main | Move to local | — | exit/cleanup prompt |
| Direct commit on the worktree branch | Review & commit panel | commit in the worktree session | commit in the worktree |
| Carry uncommitted main changes in | Include uncommitted changes toggle | — | .worktreeinclude |
| Auto-ignore the worktree directory | — | — | .gitignore tip |
How it works
Blank conversation: pick "Worktree mode" in the dock dropdown (before the
conversation starts) → optional branch name (auto-prefixed "worktree/")
│ send the first message → the host injects an instructions context block
▼ the model calls worktree_create on that same turn
│ git worktree add -b worktree/<name> <repo>/.dsh-worktrees/worktree/worktree/<name>
│ NO workspace is registered, NO conversation switch — the session header
│ badge marks the worktree this conversation uses
▼ work continues in the same conversation (the model uses absolute paths
inside the checkout); when done the model reminds you how to clean up
│
├─ /worktree bring-back worktree/<name> → merge the branch into the main branch
│ (requires a clean main workspace)
├─ /worktree finish worktree/<name> <msg> → commit on the worktree branch, keep it
└─ /worktree remove worktree/<name> --force→ delete the worktree + branch
(--force also deletes uncommitted changes)
- Start in worktree mode: on a blank conversation the dock selector shows
「Branch:」 before you send anything — picking "Worktree mode" ARMS the
session, and the branch-name field is optional (typed names are
auto-prefixed
worktree/, blank lets the model propose one). The mode
selector disappears once the conversation starts; the session-header badge
takes over the indication.
- Send your first message — the host injects one
instructions context
block (shown as 上下文注入) right before your message: create the worktree
with a worktree/-prefixed branch, work inside the checkout path, and at
the end remind the user with copy-paste cleanup commands
(bring-back or remove --force).
- Or skip the mode and ask the agent directly: "用 worktree 隔离干活，任务叫 xxx"
— the model calls
worktree_create; the name is both the branch and the
relative path (slashes allowed).
- No workspace entry is created, so the sidebar stays uncluttered. The badge
on the session header shows the branch name while the conversation is in
worktree mode.
- When done:
bring-back / finish / remove (all human-only, as above);
/worktree list / status / prune inspect and clean up (prune also
drops stale workspace registrations for removed checkouts).
Install
dsh plugin --profile web add dsh-task-worktree
Requires: DeepSeek Harness 0.1.0-rc.7 package line, Git 2.31+, Node 20+.
Model tools
| Tool | Purpose |
|---|
worktree_create {name, baseCommit?, includeUncommitted?} | Create a task worktree (name = branch and relative path, slashes allowed); optionally carry uncommitted main-workspace changes in |
worktree_list | List the repository's managed worktrees (state / dirty / branch) |
worktree_status {name?} | Status of one worktree, or the one the current session is inside |
Delivery and cleanup actions (finish / bring-back / remove) stay human-only — the model never reaches them.
Human commands
/worktree mode-on [<name>] arm worktree mode (injection with the next message)
/worktree mode-off disarm worktree mode
/worktree create <name> [<base>] [--carry]
/worktree list
/worktree status [<name>]
/worktree finish <name> <message>
/worktree bring-back <name> [<message>]
/worktree remove <name> [--force]
/worktree prune
Safety model
@deepseek-ai/* are peerDependencies only — the host supplies them; the plugin never installs infrastructure copies into a profile (a second instance breaks TOOL_RUNTIME_SCHEDULER's unique symbol and kills tool calls).bring-back requires a clean main workspace (MAIN_DIRTY) and refuses to run from inside the worktree.remove refuses the worktree the current session is working inside (IN_USE).- All git operations go through
ctx.subprocess (harness-managed); the test path uses a child_process runner.
- Manifest writes are atomic (tmp + rename);
prune drops records whose checkout no longer exists.
Local development
npm test # smoke test: full lifecycle on a scratch repository
npm pack --dry-run # inspect the tarball before publishing
License
MIT — see LICENSE
