Skip to content

dsh-worktree-plugin

Verified

dsh-worktree-plugin Β· v0.1.16 Β· MIT Β· Web UI

Git worktree and branch isolation for DeepSeek Harness

Install

dsh plugin add dsh-worktree-plugin

Confirm the layer applied with dsh --profile default --dump-config β€” see the install guide.

Source

Tags

Creators

Readme

dsh-worktree-plugin

Git worktree management with GUI picker for DeepSeek Harness β€” create, switch, and remove isolated git worktrees from the chat message box.

npm version License: MIT Cordis Plugin

Overview

dsh-worktree-plugin is a Cordis plugin for DeepSeek Harness that provides isolated git worktree management. It adds a select_branch_worktree tool to the model and a worktree picker/switcher GUI component to the chat message box.

Features

Feature Description
🌳 Create Worktrees Create isolated git worktrees from fresh, head, branch, or PR base
πŸ”„ Switch Worktrees Switch between existing worktrees from the GUI
πŸ—‘οΈ Remove Worktrees Remove worktrees you no longer need
πŸ“‹ List Worktrees View all worktrees in the current repository
πŸ–±οΈ GUI Picker Beautiful branch icon button with active worktree badge in the chat composer bar
πŸ’¬ Command Interface /worktree commands inserted into your draft
πŸ”’ Sandbox Safe Path guards and locking for safe git execution
πŸ“± Toasts Beautiful success/error/info toast notifications instead of alerts
🎨 Modal Dialogs Beautiful modal dialogs with select box for create and remove operations
πŸ”„ Auto-Refresh Worktree list auto-refreshes after create, switch, and remove operations
πŸ’Ύ Persistence Worktree records persisted to disk (<repoRoot>/.dsh/worktree-records.json) β€” survive server restarts
⏳ Loading States Spinner and disabled state during all async operations

Cordis Service Access (Host Side)

The host-side plugin accesses the WorktreeService through a captured instance (const service = new WorktreeService(ctx, config)) rather than ctx.worktree. Cordis requires explicit inject declarations for context property access; using the captured instance avoids the "cannot get property 'worktree' without inject" error while keeping the plugin activation independent of optional Cordis services.

Installation

Install from npm (recommended)

dsh plugin install dsh-worktree-plugin
pnpm dsh web

No --patch flag needed. The plugin manager auto-registers the bundle via dsh.bundle.patch in package.json.

Install from source

git clone https://github.com/MojtabaFaraji/dsh-worktree-plugin.git
cd dsh-worktree-plugin
npm install
npm run build
dsh plugin install file:///path/to/dsh-worktree-plugin
pnpm dsh web

Activation

The plugin activates automatically on pnpm dsh web after dsh plugin install dsh-worktree-plugin β€” no manual cordis.patch.yml edits needed.

If you want to customize configuration, add to your profile's cordis.patch.yml:

- insert:
    - id: worktree
      name: 'dsh-worktree-plugin'
      config:
        baseRef: fresh
        root: .dsh/worktrees
        autoCreate: false

Configuration Options

Option Type Default Description
baseRef 'fresh' 'head' 'branch'
root string '.dsh/worktrees' Directory under repo root where worktrees are stored
autoCreate boolean false Auto-create a worktree on session creation

Usage

GUI (Chat Message Box)

After activation, a branch icon button appears in the chat composer bar:

[Type your message...] [branch icon | my-worktree] [command menu]

Click the branch icon to open the worktree menu. The active worktree name appears next to the icon so you always know which worktree you're in.

Menu Item Action
Switch to main Switch to base repository (disabled when already active)
Switch to Switch to an existing worktree (disabled when already active)
Refresh list Refreshes worktree list from host
Create worktree… Opens beautiful modal to create a new worktree
Remove worktree… Opens select box modal to remove a worktree

No user knowledge of tools required. The user never needs to know about select_branch_worktree or tell the agent to call it. The plugin handles everything transparently via HTTP calls from the client GUI to the host.

The active worktree name is displayed next to the icon so you always know which worktree you're in.

Empty State & Main Worktree

When no worktrees exist, the GUI shows "main" next to the icon and "Switch to main" at the top of the menu. Create your first worktree:

"Use select_branch_worktree to create a worktree named 'Test' with baseRef 'head'"

Then click Refresh list to see it appear below "Switch to main".

Auto-Refresh

When the agent creates, removes, or lists worktrees through the select_branch_worktree tool, the host emits a worktree/changed event. The client GUI listens for this event and automatically updates the worktree dropdown β€” no manual refresh needed.

Persistence Across Restarts

Worktree records are persisted to <repoRoot>/.dsh/worktree-records.json. When you restart the web server:

  1. ensureLoaded() reads the JSON file from disk
  2. Each record is validated against git worktree list --porcelain
  3. Stale entries (worktrees that no longer exist on disk) are dropped
  4. Your worktrees reappear in the GUI β€” no re-creation needed

Automatic Tool Invocation

The plugin uses zero-agent-knowledge operation β€” GUI menu clicks auto-call the select_branch_worktree tool via HTTP to the host without the user typing commands or the agent knowing about tools:

Step Action Who
1 User clicks a menu item in the worktree picker User
2 GUI shows beautiful modal (create input or remove select box) GUI
3 Client fetches host HTTP route (/api/dsh-worktree-plugin/{create,remove,switch,list}) Client
4 Host executes git worktree operation Host
5 Host returns success/error result Host
6 GUI shows toast notification with result GUI
7 Worktree list auto-refreshes GUI

No user knowledge of tools required. The user never needs to know about select_branch_worktree or tell the agent to call it. The plugin handles everything transparently.

Fallback

If Cordis events cannot cross the client-host boundary in your deployment, the plugin falls back to inserting /worktree commands into the draft. In that case, the agent needs to call select_branch_worktree manually. The plugin uses HTTP routes on the host WebServer as the IPC mechanism between client and host contexts.

Command Interface

Each GUI action inserts a /worktree command into your draft. The model then executes it through the select_branch_worktree tool:

Command Description
/worktree create Create a new isolated worktree
/worktree switch Switch to an existing worktree
/worktree list List all worktrees in the repo
/worktree remove Remove a worktree

Creation Modes

Mode Description
fresh Creates a worktree with a fresh checkout
head Creates a worktree from current HEAD
branch Creates a worktree from an existing branch
pr Creates a worktree from a pull request

API

select_branch_worktree Tool

Parameters:

{
  "action": "create|list|switch|remove",
  "name": "worktree-slug",
  "baseRef": "fresh|head|branch|pr",
  "branch": "existing-branch-name",
  "prNumber": 123,
  "force": false
}

Client Plugin

  • Name: dsh-worktree-plugin-client
  • Slot: conversation.input.left (chat message box)
  • Order: 50

Project Structure

dsh-worktree-plugin/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ index.ts              # Host-side Cordis plugin entry
β”‚   β”œβ”€β”€ types.ts              # Shared types and Context augmentation
β”‚   β”œβ”€β”€ worktree-service.ts   # Git worktree service implementation
β”‚   β”œβ”€β”€ schemas.ts            # Input validation schemas (Zod)
β”‚   └── client/
β”‚       β”œβ”€β”€ index.ts          # Client-side Cordis plugin
β”‚       └── WorktreePicker.tsx # React GUI component
β”œβ”€β”€ lib/                      # Built output (published to npm)
β”œβ”€β”€ tsconfig.json             # Host-side TypeScript config
β”œβ”€β”€ tsconfig.client.json      # Client-side TypeScript config
β”œβ”€β”€ tsdown.config.ts          # Client bundle config
β”œβ”€β”€ cordis.patch.yml          # Cordis plugin insertion manifest
β”œβ”€β”€ package.json              # npm package manifest
β”œβ”€β”€ README.md                 # This file
β”œβ”€β”€ LICENSE                   # MIT License
└── .gitignore                # Git ignore rules

Development

# Install dependencies
npm install

# Build host-side (TypeScript)
npx tsc -p tsconfig.json

# Build client-side (TypeScript + tsdown bundle)
npx tsc -p tsconfig.client.json
npx tsdown --env.DSH_BUILD_FACE client

Publishing to npm

npm publish --access public

Requirements

  • DeepSeek Harness with Cordis runtime
  • React 18+ (peer dependency)
  • @deepseek-ai/dsh-client-ui-conversation (peer dependency)
  • @deepseek-ai/dsh-client-ui-primitives (peer dependency)
  • Git (for worktree operations)

License

MIT License β€” see LICENSE for details.

Repository

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

Support

For issues and feature requests, please open an issue on GitHub.