dsh-worktree-panel

Readme

# dsh-worktree-panel

<p align="center">
  <a href="https://www.npmjs.com/package/dsh-worktree-panel"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-worktree-panel?label=npm&color=blue"></a>
  <a href="https://www.npmjs.com/package/dsh-worktree-panel"><img alt="monthly downloads" src="https://img.shields.io/npm/dm/dsh-worktree-panel?label=downloads&color=brightgreen"></a>
  <a href="https://github.com/HeathHe/dsh-worktree-panel"><img alt="stars" src="https://img.shields.io/github/stars/HeathHe/dsh-worktree-panel?style=social"></a>
  <a href="https://github.com/HeathHe/dsh-worktree-panel/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/github/license/HeathHe/dsh-worktree-panel?color=orange"></a>
  <img alt="platform" src="https://img.shields.io/badge/platform-DeepSeek%20Harness%20Web-8A2BE2">
</p>

<p align="center">
  <strong>English</strong> | <a href="./README.zh-CN.md">简体中文</a>
</p>

A Git worktree and branch-management panel for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web GUI. It extends the official workspace/session sidebar with a **project → main working tree / branch worktree → session** hierarchy while preserving the original workspace interactions.

---

## Usage

### Install

```sh
dsh plugin --profile web add dsh-worktree-panel
```

Restart `dsh web` after installation. The worktree hierarchy will then appear in the workspace sidebar.

Install a specific version:

```sh
dsh plugin --profile web add dsh-worktree-panel@0.1.5
```

### Upgrade

```sh
dsh plugin --profile web add dsh-worktree-panel@<version>
# Restart dsh web afterwards.
```

### Local development

```sh
dsh plugin --profile web add link:/absolute/path/to/dsh-worktree-panel
```

---

## Features

- **Main working tree + branch worktrees** — displays the main working tree, current branch, clean/modified state, and linked branch worktrees inside each project group.
- **Session management** — starts sessions inside a worktree, removes worktrees, and switches the main working tree branch.
- **One-click creation** — creates a worktree for an existing branch or creates a new branch and its worktree.
- **Session-first non-Git folders** — the project-row plus button starts a conversation directly. “Initialize Git and enable worktrees” is available from the project actions menu.
- **Configurable storage** — stores worktrees in `<project>/.dsh/workspaces/` by default or in a custom global directory.
- **Safe migration** — detects and migrates existing worktrees when the storage location changes, while skipping worktrees with uncommitted changes or active sessions.
- **Progressive enhancement** — non-Git workspaces retain the default session workflow and only gain an optional Git/worktree initializer.

---

## Compatibility

- Tested with **DSH Desktop 2.0.3 / DeepSeek Harness 0.1.1-rc.2**.
- DSH peer dependency range: `>=0.1.1-rc.2 <0.2.0`.
- Uses a dedicated Worktree settings page through `settings.section`.
- Supports the current Host description store and home-directory path abbreviation.

### Generated client bundle

`lib/client.js` is generated by `lib/build.mjs` from the official `@deepseek-ai/dsh-client-ui-workspace` browser bundle. The build validates the upstream package version and records it in the generated file header.

Use an explicit upstream bundle when needed:

```sh
DSH_WORKSPACE_BUNDLE=/absolute/path/to/client.js npm run build
```

---

## License

MIT. `lib/client.js` is derived from `@deepseek-ai/dsh-client-ui-workspace`; see `NOTICE` and `LICENSE`.