dsh-worktree-plugin
Verifieddsh-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.
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:
ensureLoaded()reads the JSON file from disk- Each record is validated against
git worktree list --porcelain - Stale entries (worktrees that no longer exist on disk) are dropped
- 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.