dsh-git-workbench

dsh-git-workbench

A git development workbench for DeepSeek Harness: not a git-status display plugin — it drives the branch/worktree workflow. It captures the repository state (branch, ahead/behind, worktree status, worktrees, stashes, recent commits) into every session, asks which branch or worktree to develop in at new-session start, and switches branches / creates and manages worktrees through /git commands, the git_workbench agent tool, and a Settings page.

Features

• Automatic git context (read-only, always on) — every session in a git repository gets a compact context block injected at the first step (and refreshed after git-workbench writes): current branch, ahead/behind vs upstream, working-tree status (staged / modified / untracked / conflicts), worktree list, stash list, recent commits. Non-git directories stay silent.
• New-session environment choice (skippable) — with autoAsk on, the agent asks once per session which environment to develop in: stay on the current branch, switch to another branch, create a new branch, open an existing worktree, or create a new worktree. The user can skip (stay where they are).
• /git slash commands
  • /git status — inject the current git context snapshot
  • /git switch <branch> [--stash|--force] — switch branch
  • /git merge <target> — merge the current branch into
  • /git branch <name> [--from <base>] — create a branch and switch to it
  • /git log [N] — recent commits
  • /git stash [push|list|pop|drop] — stash management
  • /git worktree list · add <branch> [--from <base>] [--dir <path>] · remove <path|branch> [--force] [--delete-branch]
• git_workbench agent tool — the same guarded operations, callable by the agent (e.g. from the auto-ask flow). Agent-driven switching goes through exactly the same guardrails as the command.
• Sidebar Git panel (Web) — a "Git" button in the sidebar footer opens a workbench overlay: pick any registered DSH workspace, see its branch / ahead-behind / working-tree status / worktrees / stashes / recent commits live, and run guarded actions (switch branch, new branch, new worktree, remove worktree, stash push/pop/drop) with one click. Dirty-tree decisions surface inline (stash first / force / cancel).
• Composer git strip (Web) — above the input box (new-session hero and every session) a git strip shows the current workspace's branch and clean/dirty state, with an environment dropdown: use the current branch (default) / create a new branch / create a new worktree. The create options are disabled while the tree has uncommitted changes (with a "stash now" shortcut); creating a worktree registers the new directory as a workspace and offers "open a session in the new worktree".
• Merge & cleanup policy (agent rule) — when the current branch is not the main branch (auto-detected: main → master → develop), the agent follows a persistent rule: if you ask to merge to main / ship / release / go live, it merges the current branch into main with git_workbench (action merge, which also handles the target being checked out in another worktree, dirty-tree guards, and already-merged detection), then asks you whether to delete the branch/worktree after the merge or keep it, and only deletes with your explicit choice.
• Guardrails
  • Switching branches over a dirty tree is blocked; the tool returns needsDecision with options (stash first / force / cancel). Force is gated by allowForceSwitch (default off).
  • Removing a worktree never targets the main worktree or this session's working directory; dirty worktrees need --force, gated by allowForceWorktreeRemove (default off). Optionally deletes the branch after removal (--delete-branch, only when merged).
  • All git execution uses execFile with an argument array — no shell, so names cannot inject commands. Branch names are sanitized.
• Settings → Plugins → Git Workbench — autoAsk, ask threshold, worktree directory template ({parent}/{repo}-{branch}), recent-commit count, and the two force toggles. Persisted to $DSH_HOME/git-workbench.json.

Quick start

dsh plugin --profile web add dsh-git-workbench

Slow npm registry? dsh plugin --profile web add dsh-git-workbench --registry=https://registry.npmmirror.com

Install from a local checkout (development):

dsh plugin --profile web add file:/path/to/dsh-git-workbench

Use the file: prefix (copies the package into node_modules). A bare add . or add link:… makes pnpm symlink the package, in which case the plugin's schemastery dependency resolves from the source checkout and is not found — a general pnpm symlink-install gotcha, not a bug in the plugin.

Restart dsh web, then:

1. Open a session in a git repository → you should see the git context injected, and (with ≥2 branches/worktrees) the environment question at the start (skippable);
2. Or type /git for the command menu.

Worktree workflow

Worktrees are separate directories, so in DSH each worktree is its own workspace/session. /git worktree add <branch> creates the worktree at <parent>/<repo>-<branch> (configurable via worktreeDirTemplate) and tells you to open a new DSH session in that directory — that is the intended way to "develop in a worktree". The worktree is immediately visible in the worktree list of every other session of the same repository.

Implementation notes (for plugin authors)

• Do not import @deepseek-ai/* from an out-of-tree host plugin. Declaring @deepseek-ai/dsh-llm / dsh-tools (or any @deepseek-ai/*) as dependencies installs second copies into the profile's node_modules; the resulting duplicate module instances break host module identity (empirically: the tools scheduler's TOOL_RUNTIME_SCHEDULER symbol mismatch makes every tool dispatch fail with Cannot read properties of undefined (reading 'prepare')). This plugin therefore hand-builds its pre-step context message (the createUserMessage shape: id + role:'user' + content + source:{kind:'plugin',plugin,form:'snapshot',sections}, deep-frozen) and registers its agent tool as a plain compiled definition (parameters as an object-rooted JSON Schema with a root required array; output as a strict JsonSchemaNode).
• The injected context uses the dsh-time-context pre-step pattern: ctx.on('agent/pre-step', …, { prepend: true }), fresh capture on step 1, memoized between steps, re-injected when the fingerprint changes or after our own writes.
• git status --porcelain=v2 does not emit # branch.* header lines unless --branch is passed.

Test

npm test   # 49 unit + real-git integration tests (temp repos)