dsh-git-branch

Readme

# dsh-git-branch

English | [中文](README.zh.md)

Show the current workspace **git branch** right after the composer **mode** controls (access mode / plan) in the DeepSeek Harness (DSH) Web UI. It renders only when the workspace is inside a git repository, and it refreshes automatically when you switch branches in another tool.

## Where it appears

The composer tool row is laid out as `[+ commands] [access mode] [plan] ← branch chip`. This plugin registers into the `conversation.input.left` slot — the additive seat immediately after the resident mode chrome — so the branch chip sits right next to the mode controls.

- Branch: `⎇ main`
- Detached HEAD: `⎇ detached @ a1b2c3d`
- Not a git repository: nothing renders
- Click the chip: refresh immediately (tooltip explains)

## Install

The package is a DSH **bundle** (it ships its own `cordis.patch.yml`), so `dsh plugin add` both installs the dependency and activates it — no manual config:

```bash
# from npm
dsh plugin --profile web add dsh-git-branch

# or a local checkout (development)
dsh plugin --profile web add ./dsh-git-branch
```

Then restart the profile and refresh the page:

```bash
# restart dsh web, then reload the browser tab
```

> How it works: `package.json` declares `dsh.bundle.patch = ./cordis.patch.yml`, which `- insert`s one `git-branch` plugin row. `dsh plugin add` detects `dsh.bundle` and adds the package to `dsh.profile.bundles`; on the next boot that patch layer takes effect, the host loads the host half, and the client half is served to the browser automatically.

### Optional host config

To change the command name, override the row (same id) in your own profile `cordis.patch.yml`:

```yaml
- id: git-branch
  name: dsh-git-branch
  config:
    commandName: git-branch   # optional; default is git-branch
```

Unknown config keys fail at load.

### Client refresh constant

See the top of `src/client/index.tsx` (or `lib/client.js`):

- `POLL_INTERVAL_MS = 60000`: slow safety-net poll; `<= 0` disables it.

## How it works

- **host**: `lib/index.js` registers the `/git-branch` command; the handler walks up from `session.header.cwd` to the nearest `.git` (worktrees and submodules included), parses `HEAD`, and returns the result as JSON in the command's `text` field.
- **client**: `lib/client.js` registers the `conversation.input.left` chip, fetches the branch through `ctx.remote.commands.execute`, and registers a `conversation.chat.commandview` entry for `git-branch` that renders `null`, hiding the transport command from the transcript.

Refresh triggers (see [DESIGN.md](./DESIGN.md)): mount / session-or-workspace switch → immediate; window `focus` → immediate; `visibilitychange → visible` → immediate; chip click → immediate; 60s poll → fallback.

## Layout

```
dsh-git-branch/
├── package.json          # dsh.bundle + dsh.client + peerDependencies
├── cordis.patch.yml      # bundle patch: inserts the git-branch plugin row
├── LICENSE
├── src/
│   ├── index.ts          # host half (TypeScript source)
│   └── client/index.tsx  # client half (TypeScript source)
├── lib/
│   ├── index.js          # host half (prebuilt)
│   ├── index.d.ts
│   ├── client.js         # client half (prebuilt, window.__ModuleLoader__ format)
│   └── client.d.ts
├── DESIGN.md             # git-branch refresh-rules design
├── README.md             # English (this file)
└── README.zh.md          # 中文
```

## License

MIT