Preface

Under the DSH “everything is a plugin” philosophy, dsh-worktree is integrated as a plugin. It solves a specific problem: when multiple DSH sub-agents process the same repository simultaneously, parallel writes are prone to interference. This plugin enables sub-agents to work within independent Git worktrees. After the task is complete, users can review, verify, commit, merge, push, create Pull Requests, archive, or restore results.

What is This

The repository owner is paradoxSCH, and the repository address is:

https://github.com/paradoxsch/dsh-worktree

Package information is as follows:

@paradoxsch/dsh-worktree
0.1.0-alpha.2
MIT

The Node requirement declared in package.json is:

>=22.19.0

The current alpha version supports the released DSH:

0.1.0-rc.6
0.1.x

The plugin is installed to the global DSH profile and does not modify the package.json of business projects.

Installation and Enabling

First, select the DSH profile to install, then execute the installation command.

Web profile:

dsh plugin --profile web add @paradoxsch/dsh-worktree@alpha

Headless profile:

dsh plugin --profile headless add @paradoxsch/dsh-worktree@alpha

After installation, you can check if the current profile can see this plugin:

dsh plugin --profile web why @paradoxsch/dsh-worktree
dsh --profile web --dump-config

Typical Usage

Delegating Sub-agents

By instructing the Agent to use the following delegation capability, the sub-agent will automatically enter an independent worktree:

subagent_worktree

If the task requires parallel execution, you can set:

run_in_background: true

Afterward, use DSH’s task interface to view results or stop the task:

job_output
job_kill

Manual Worktree Management

You can also manually manage worktrees using the /worktree command. Common commands are as follows:

/worktree list
/worktree create working-state managed
/worktree review <id>
/worktree validate <id>
/worktree doctor
/worktree recover

The <id> in the commands refers to a specific worktree identifier.

Review and Delivery

/worktree supports the following delivery operations:

/worktree review <id>
/worktree validate <id>
/worktree commit <id> <message>
/worktree branch <id> <branch-name>
/worktree handoff <id>
/worktree merge <id>
/worktree push <id>
/worktree pr <id> <title>
/worktree archive <id>
/worktree restore <id>
/worktree discard <id> confirm

These commands cover the paths for review, verification, commit, branch, delivery, merge, push, Pull Request, archive, and restore.

Task Start Point and Retention Mode

When creating a worktree, the following mode values are supported:

working-state
head
fresh
ephemeral
managed
permanent

Among them, working-state, head, and fresh are used to select the task start point; ephemeral, managed, and permanent are used to select the retention mode.

Regarding sensitive files, the confirmed behavior is:

  • ignored files are not copied by default.
  • Sensitive content such as .env, keys, and certificates will not be copied even if listed in .worktreeinclude.

Security and Recovery

Confirmed security constraints include:

  • Worktrees with modifications will not be automatically discarded.
  • Operations such as delete, merge, commit, push, and Pull Request will re-check the worktree status before execution.
  • push does not use force.
  • merge requires the target checkout to be clean.
  • worktree resolves parallel write conflicts but does not replace DSH sandbox or approval policies.

Creating a Pull Request requires a logged-in GitHub CLI. You can check this first:

gh auth status

Default persistence data is located at:

$DSH_HOME/plugins/dsh-worktree

Environment diagnostics and state recovery can be performed using:

/worktree doctor
/worktree recover

Use Cases and Notes

Suitable for having multiple sub-agents process the same repository in parallel within DSH, while ensuring each task has an independent checkout and retaining reviewable, deliverable, and recoverable results after the task is complete.

Notes:

  • This plugin runs with the permissions of the current DSH process; you should check the source code, package.json, and the MIT license before installing.
  • The plugin is installed to the global DSH profile and does not modify the package.json of business projects.
  • Uninstalling the bundle will not delete retained or archived results.

Uninstallation

Uninstallation commands are as follows:

dsh plugin --profile web remove @paradoxsch/dsh-worktree
dsh plugin --profile headless remove @paradoxsch/dsh-worktree

After confirming that you no longer need the retained or archived results, handle them separately:

$DSH_HOME/plugins/dsh-worktree

Conclusion

The main value of dsh-worktree is to isolate the parallel writes of DSH sub-agents into independent Git worktrees and provide a delivery pipeline for review, verification, commit, merge, push, Pull Request, archive, and restore. To view source code, license, or report issues, please visit:

https://github.com/paradoxsch/dsh-worktree