Introduction

In the DSH plugin extension, a common issue arises when multiple sub-agents process the same repository simultaneously, as their working directories can easily interfere with each other. dsh-worktree addresses this by allowing each sub-agent to enter its own git worktree: sharing the repository object database, but keeping the workspaces independent of each other.

Below is an introduction to the plugin’s positioning, installation methods, typical usage, and known limitations.

What is this

dsh-worktree is a DeepSeek Harness plugin designed to provide filesystem isolation based on git worktrees for DSH sub-agents.

  • GitHub Repository: CSY656/dsh-worktree
  • Package Name: dsh-worktree
  • Owner: CSY656
  • License: MIT
  • Version Requirement: DeepSeek Harness next line, dsh >= 0.1.0-rc.6

It provides two entry points: the ctx.worktree service for plugin authors, and the /worktree slash command for users.

Core Features

Isolation Location and Naming

Worktrees are located at:

<repoRoot>/.dsh/worktrees/<flatSlug>/

If the slug is nested, / is flattened to +. For example:

feature/demo → feature+demo
team/alice   → team+alice

The corresponding branch uses worktree-<flatSlug>, for example:

worktree-feature+demo

Slug Validation

Before creating a worktree, the slug is strictly validated:

  • Each segment is limited to [a-zA-Z0-9._-]
  • Each segment length does not exceed 64
  • Rejects . and .. and //
  • Rejects leading and trailing separators

Best-effort Configuration After Creation

After a worktree is created, the plugin attempts to perform setup:

  • Copies the project .dsh configuration
  • Inherits core.hooksPath
  • Symbolically links node_modules, .venv, vendor
  • Copies ignore files listed in .worktreeinclude

Change Protection

Change detection uses a fail-closed approach: git failures are treated as “has changes”. Therefore, dirty worktrees are preserved and reported rather than being deleted immediately.

Temporary Worktree Cleanup

The plugin supports configuration for:

  • sweepIntervalMs
  • sweepMaxAgeMs

Used to periodically clean up agent-* temporary worktrees.

Installation and Enablement

Install from GitHub

dsh plugin --profile default add github:you/dsh-worktree

Handling pnpm >= 10

If using pnpm >= 10, you need to allow builds in the profile’s pnpm-workspace.yaml:

allowBuilds:
  dsh-worktree: true

Then run the add command again.

npm Prebuilt Installation

The README also provides an npm prebuilt installation command:

dsh plugin --profile default add dsh-worktree

Pre-installation Checks

dsh-worktree runs with the permissions of the current DSH process. Before installing, it is recommended to check the source code, license, and dependencies to ensure the behavior meets your security requirements.

Typical Usage

Slash Commands

/worktree create feature/demo
/worktree list
/worktree remove feature/demo

Corresponding behaviors:

  • /worktree create feature/demo: Creates .dsh/worktrees/feature+demo, branch is worktree-feature+demo
  • /worktree list: Outputs name/path/branch lines
  • /worktree remove feature/demo: Refuses to delete when the worktree is dirty; add --discard to force

Service API

Plugin authors can create and manage worktrees via the ctx.worktree service:

const lease = await ctx.worktree.acquire('agent-abc1234', cwd)

// ... pass the worktree path to an independent sub-agent to execute ...

const { kept, path, branch } = await lease.release()

After release:

  • Clean worktrees are removed
  • Dirty worktrees are preserved and reported

Applicable Scenarios and Notes

Suitable for scenarios where multiple sub-agents need to modify the same repository in parallel without directly overwriting the same workspace.

Limitations during use are as follows:

  • Only in-process isolation is effective; out-of-process backends like acp, claude-code, codex, dsh-sdk will ignore child-session cwd overrides
  • No cross-process sharing; a DSH instance owns its worktrees
  • No merge strategy; the retained worktrees are merged by the delegated agent, for example:
git merge worktree-<flatSlug>
  • One-line subagent automatic isolation requires upstream capabilities from dsh-subagent/dsh-tool-subagent; until those are accepted upstream, you must manually use ctx.worktree.acquire() or the /worktree command

Conclusion

The value of dsh-worktree lies in applying filesystem isolation for DSH sub-agents to git worktrees, and lowering the risk of accidentally deleting dirty workspaces through fail-closed change protection.

It is an independent plugin within the DSH plugin ecosystem; the community directory is an independent site with no official affiliation with DeepSeek/Huafan, and should not be interpreted as an official app store.

The verified materials for this session do not provide a confirmable directory page URL; the GitHub repository is at https://github.com/CSY656/dsh-worktree.