dsh-plugin-worktree
A dsh plugin that brings
Claude Code-style git worktree support to the dsh web UI. Create, switch, and
delete worktree-backed sessions without leaving the browser.
Features
- New-session hero — the workspace chip shows the root workspace name when the current session is in a worktree, and the Worktree chip shows the current worktree name. You can list the repository's worktree workspaces, create a new git worktree, or switch to another worktree.
- Sidebar badge — worktree workspaces are normal workspaces whose titles carry a
⑂ branch badge.
- Delete dialog — deleting a worktree workspace asks whether to also remove the git worktree directory and its
dsh/<name> branch, or keep them on disk.
Requirements
- A working dsh installation
- A
web profile (dsh web)
git available on the host machine- Node.js 18 or newer
Install
From npm
dsh plugin --profile web add dsh-plugin-worktree
Restart dsh web. The plugin registers the worktree bundle row automatically.
From GitHub
dsh plugin --profile web add github:limoiie/dsh-plugin-worktree#main
Pin a released version by replacing #main with a tag, for example:
dsh plugin --profile web add github:limoiie/dsh-plugin-worktree#v0.1.0
Git-hosted installs may need pnpm's allowBuilds approval for the package's
prepare script, as pnpm prints during installation.
Update
dsh plugin --profile web update dsh-plugin-worktree
Restart dsh web after updating.
If you installed from GitHub, re-run the same GitHub install command to move to
the latest commit of that branch or tag.
Remove
dsh plugin --profile web remove dsh-plugin-worktree
Restart dsh web after removing. This uninstalls the plugin and removes its
bundle layer from the web profile.
Quick start
- Install the plugin and restart
dsh web.
- Open a new session.
- In the workspace picker, open the Worktree chip.
- Choose New worktree…, enter a name such as
feat/okta-sso, and confirm.
- dsh creates a git worktree at
.dsh/worktrees/<name> on a dsh/<name> branch and opens a new session inside it.
To switch later, start another new session and pick an existing worktree
workspace from the Worktree chip or the sidebar. To remove a worktree
workspace, use the sidebar delete flow and choose whether to also remove the
git worktree and its branch.
Configuration
The worktree row accepts:
| field | default | meaning |
|---|
root | process.cwd() | directory used for git rev-parse --show-toplevel |
worktreesDir | .dsh/worktrees | worktree root; absolute, or relative to the repository top |
Name rules: at most 64 characters, one or more /-separated segments made of
letters, digits, dots, underscores, and dashes (feat/okta-sso works; . and
.. segments are rejected).
Users can override these values in their profile or home cordis.patch.yml by
targeting id: worktree without editing the plugin.
How it works
- The host service exposes
worktree/create, worktree/remove, worktree/removeWorktree, and worktree/branchExists RPCs.
- Creating a worktree runs
git worktree add -b dsh/<name> <repo>/.dsh/worktrees/<name> HEAD.
- The browser client registers the worktree path as a normal DSH workspace and opens a new session inside it.
- Deleting a worktree workspace asks whether to remove the git worktree and/or its branch before removing the workspace registration.
See Architecture for implementation details.
Safety
- Worktree names are validated to prevent path traversal and invalid git names.
- Worktree paths are resolved under the configured worktrees directory; paths that escape it are rejected.
- Branch deletion uses
git branch -d, so git refuses to delete branches with unmerged commits; the client surfaces that as “branch kept”.
- The configured worktrees directory is added to
.git/info/exclude on a best-effort basis so main-checkout status stays clean.
Related plugins
The dsh ecosystem already has several worktree plugins. They are not direct
replacements for each other: they emphasize different parts of the workflow,
so the right choice depends on whether the worktree is primarily for the
human in the web UI, for parallel agent tasks, or for durable
agent-created workspaces.
| Plugin | Focus | Primary interface | Worktree model | Best for |
|---|
| dsh-plugin-worktree (this plugin) | Human-first, web-native worktree sessions | dsh web: new-session hero chip, sidebar ⑂ badges, delete dialog | Regular DSH workspaces created in .dsh/worktrees/<name> on a dsh/<name> branch | Starting focused sessions in dedicated worktrees and managing them from the dsh web UI, with a clear choice to keep or remove the git worktree and branch on delete |
| dsh-plugin-worktrees | Agent-first parallel task isolation | worktree_* agent tools | Task-scoped worktrees with a serial merge queue and conflict-scene retention | Dispatching parallel subagents into isolated checkouts and integrating their branches one at a time |
| dsh-worktree | Durable, Codex-style worktrees | worktree_* agent tools and /worktree command | Permanent detached checkouts recorded in a per-repo manifest | Having the agent create, list, and reopen long-lived worktrees across sessions without touching the main checkout |
This plugin intentionally keeps the scope on the web UI workflow: a worktree
is just a DSH workspace, so creating one is also creating a session context,
the branch badge makes worktree sessions recognizable in the sidebar, and
deleting asks explicitly whether to remove the worktree directory and its
dsh/<name> branch or keep them on disk. It complements agent-tool and
merge-automation plugins rather than competing with them.
Documentation
Development
npm install
npm test
See Development for the full local setup.
License
MIT
