dsh-plugin-worktree

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

1. Install the plugin and restart dsh web.
2. Open a new session.
3. In the workspace picker, open the Worktree chip.
4. Choose New worktree…, enter a name such as feat/okta-sso, and confirm.
5. 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

• Getting started — install, verify, and configure
• Architecture — how the plugin works
• Development — set up a local checkout and iterate
• Release — versioning, publishing, and store registration
• Contributing — branch flow and contribution guidelines

Development

npm install
npm test

See Development for the full local setup.

License

MIT