Skip to main content

dsh-web-ui/packages/dsh-git-graph

5.1kStars311Forks49Issues5Watchers

Add a workspace branch selector capsule and Git graph panel to dsh web GUI blank sessions: search branches, switch branches, create new branches, view lane-style commit graphs; git operations execute on the host.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the zhu1090093659/dsh-web-ui monorepo — stars and activity count the whole repository.

Language
TypeScript
License
Apache-2.0
Branch
dev
deepseek-harnessdshdsh-pluginweb-ui

Install

cmdweb profile
$ dsh plugin --profile web add @linxin666/dsh-client-ui-git-graph

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin zhu1090093659/dsh-web-ui/packages/dsh-git-graph for me: review the repository at https://github.com/zhu1090093659/dsh-web first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

Adds a workspace branch selection capsule and Git graph panel to the dsh web GUI blank session: search local branches, view current HEAD, create and switch, view lane-style commit history—all git operations execute on the real working tree of the host process.

Core Capabilities

  • Provides a branch capsule on the right side of the blank session input area; when opened, it's a searchable popover: current branch checked off, search by name, two actions at the bottom—"Create and checkout new branch…" and "Git Graph"
  • Branch switching operates on the workspace-level real git switch --no-guess: affects all sessions in that workspace; guards against three scenarios: unresolved conflicts, ongoing git operations, target branch already checked out by another worktree
  • New branch creation goes through git switch --no-guess -c, supports create dialog: client does instant validation first (cannot start with -, cannot contain .. / ~^:?*[\), host then does authoritative validation with git check-ref-format --branch
  • Git Graph panel renders commit history in lane style (topo-order + parents), each row with author, time, relative time (just now / N minutes ago / N hours ago / N days ago), supports loading more
  • Status refresh is three-way stacked: capsule mount / popover open / switch success each pull once; during subscription, host polls workspace every 30 seconds (pushes only changes, 15s timeout fallback); window focus pulls an additional time (5s throttle)
  • SSE long connection goes through cross-tab master selection (Web Locks + BroadcastChannel), same URL keeps only one EventSource across the entire browser, avoiding multi-tab contention for HTTP/1.1 same-origin connection pool

Technical Implementation

  • Language: TypeScript (host half) + TypeScript + React 18 + CSS Modules (browser half)
  • Key Dependencies: react ^18.2.0 (peer, injected by host runtime), @deepseek-ai/dsh-client-ui-conversation (provides SlotMap and input area slots), @deepseek-ai/dsh-client-ui-slots (slot registration), @deepseek-ai/dsh-host-webserver (host routing and SSE framework)
  • Architecture Pattern: Dual-half cordis bundle. src/index.ts is the host half (mountOnce single-instance guard + registers /git/* routes + mounts GitService); src/client/index.ts is the browser half (declarative-aware mount: waits 2 seconds first to see if shell declares conversation.input.selector.context slot, late arrivals permanently fall back to conversation.input.dock hero phase; active sessions don't mount). All git calls go through host's subprocess service (production uses /git/* HTTP + SSE, tests use plain child_process)
  • Entry Files: packages/dsh-git-graph/src/index.ts (host entry, cordis apply), packages/dsh-git-graph/src/client/index.ts (browser entry, cordis client apply); cordis bundle declaration in packages/dsh-git-graph/cordis.patch.yml:1-12 (inserts id ui-git-graph), browser dependencies in packages/dsh-git-graph/package.json:34-46 (injects 3 official @deepseek-ai/dsh-client-* modules + platform: web)

Use Cases

  • Users doing multi-branch parallel development on dsh web: before opening a new session, click the branch capsule on the blank panel, search/switch to the branch you want to use, avoid manually running git switch for each session;
  • Users who want to visualize their workspace commit history: click "Git Graph" at the bottom of the capsule to open the lane graph panel, see at a glance which branch is on which line, whether there are forks, more intuitive than git log --graph;
  • Users who prefer conversation-driven development and want toolbar style aligned with official workspace capsules: this plugin's capsule follows the same 28px transparent capsule recipe and --dsw-* theme tokens as official WorkspaceChip / AgentPresetSeat, installed visual style won't jump.

Prerequisites & Compatibility

DependencyMin VersionDescription
DSH Host0.1.0-rc.6+ recommendedpackage.json doesn't declare in dsh.engines; devDependencies uniformly locked to @deepseek-ai/dsh-* ^0.1.0-rc.8
Node.js^22.19.0 or >=24.0.0package.json engines.node
PlatformCross-platform (host side PATH must resolve git; Windows explicitly uses git.exe)Host half runs in Node.js, client half runs in browser, no OS restrictions
Native ModulesNone (runtime)Spawns git binary through host's subprocess service, no native bindings introduced
Git BinarySystem PATH reachablehost side git --version must be available; Git for Windows recommended on Windows
React^18.2.0peerDependency, injected by host

Installation

dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-git-graph

Configuration

This plugin requires no user configuration.

There are a few tunable constants in the host source code (such as polling cadence, fallback wait, request body limit), but none are exposed to the DSH settings panel—adjustment requires source code modification and rebuild:

Internal ConstantLocationDefaultPurpose
POLL_INTERVAL_MShost/routes.ts:4930000 msInterval for host to poll workspace status during SSE subscription
HEARTBEAT_INTERVAL_MShost/routes.ts:5115000 msSSE heartbeat interval (prevents proxy dropping empty connections)
STATUS_TIMEOUT_MShost/routes.ts:5815000 msTimeout fallback for single git status; kills subprocess with AbortController on timeout
BODY_CAP_BYTEShost/routes.ts:751 MiBRequest body limit for /git/*; destroys connection if exceeded
CONTEXT_FALLBACK_MSclient/index.ts:942000 msDuration client waits for shell to declare conversation.input.selector.context slot; falls back to conversation.input.dock on timeout
FOCUS_REFRESH_MIN_MSclient/chips/BranchChip.tsx:325000 msThrottle interval for re-fetching branch status when browser window gains focus

FAQ

Q: After installation, the branch capsule doesn't appear in the input area. What should I do?

A: Three-step排查. First, confirm dsh web has been restarted—bundle activation happens once at startup, refreshing the browser isn't enough. Second, check if the browser console has errors related to [dsh-git-graph] or slot declaration. Third, wait about 2 seconds—the plugin waits 2 seconds for shell to declare conversation.input.selector.context slot before falling back to dock hero phase; if shell hasn't declared this hole, the capsule will automatically appear on the hero row to the right of agent-preset seat (late declarations are ignored). See packages/dsh-git-graph/src/client/index.ts:184-199.

Q: Getting blocked by tracked-changes-would-be-overwritten when switching branches. What to do?

A: This is git's own protection: local changes to tracked files would be overwritten by the target branch. The error lists the first two blocking file paths plus the count of remaining files. This plugin doesn't do automatic stash (to avoid accidentally swallowing your changes), please git stash or git commit first before switching. Error classification in packages/dsh-git-graph/src/host/git-service.ts:87-152, copy in packages/dsh-git-graph/src/client/locales.ts:30-35.

Q: I have multiple Git repositories in my workspace. Which one does this capsule manage?

A: It manages the one where the current session's cwd is located. It reads the session baseline's cwd, resolves to repoRoot via git rev-parse --show-toplevel, all git switch operations act on that repoRoot. Switching workspace = activating target workspace and opening its (reused or new) blank session, won't modify other sessions' cwd. Semantics in packages/dsh-git-graph/src/client/index.ts:122-132 and packages/dsh-git-graph/README.zh.md:74.

Q: Will switching branches affect other sessions that are already running?

A: Yes, because it switches the workspace-level disk tree—all sessions share the same checkout. If you just want a specific session to work on another branch, the correct approach is to switch to the target workspace in the workspace capsule in the input area (or create a new blank session), not use this plugin's branch capsule. See packages/dsh-git-graph/src/host/git-service.ts:204-225 / packages/dsh-git-graph/README.zh.md:74.

Q: Does every switch succeed? What situations cause rejection?

A: Three types of guards block: unresolved merge conflicts (conflicts-present), ongoing git operations (merge / rebase / cherry-pick / revert / bisect any flag present → operation-in-progress), target branch already checked out by another worktree (branch-in-other-worktree). These three directly reject with readable error messages, won't silently force switch. Guards in packages/dsh-git-graph/src/host/git-service.ts:323-340, error copy in packages/dsh-git-graph/src/client/locales.ts:27-29.

Q: Opening two tabs with the same URL, will it exhaust the browser's HTTP connections?

A: No. SSE long connection goes through cross-tab master selection (Web Locks + BroadcastChannel), same URL keeps only one EventSource across the entire browser, other tabs receive events via BroadcastChannel, HTTP/1.1 same-origin connection pool isn't crowded. Falls back to each subscription getting one connection (old behavior) if browser supports neither Web Locks nor BroadcastChannel. Code in packages/dsh-git-graph/src/client/sse-leader.ts:45-122 (corresponds to issue #383).

Q: What happens when creating a new session in a non-Git directory?

A: The capsule simply doesn't display—when git rev-parse --show-toplevel fails on host side, RepoStatus returns null, frontend receives null and doesn't render the control; no error, no empty block. Logic in packages/dsh-git-graph/src/host/git-service.ts:281-286, packages/dsh-git-graph/src/client/index.ts:134-138.

Q: Will git status change after uninstalling the plugin?

A: No. This plugin doesn't write any persistent files on host, branch switching goes through disk git switch, all state is managed by git itself. Uninstalling dsh plugin --profile web remove @linxin666/dsh-client-ui-git-graph won't leave any plugin residual state. Uninstall command in packages/dsh-git-graph/README.zh.md:65-67.

Getting Started Difficulty

Beginner — one-line command install, restart dsh web to see the branch capsule; automatically hidden in non-Git directories, no extra configuration needed.

Known Issues & Limitations

  • Client only waits 2 seconds for conversation.input.selector.context slot declaration, after timeout permanently falls back to conversation.input.dock hero phase; late declarations are ignored, won't retry until host restarts (packages/dsh-git-graph/src/client/index.ts:191-199)
  • Active sessions don't show branch selection control, branch switching requires creating a new blank session or restarting host (packages/dsh-git-graph/src/client/index.ts:7-9)
  • No automatic stash before branch switching, dirty worktree will be rejected by git itself (packages/dsh-git-graph/src/host/git-service.ts:207-225)
  • Windows forcibly uses git.exe (avoids .cmd shim, prevents % in --format string from being expanded by cmd.exe), cannot be overridden in config (packages/dsh-git-graph/src/host/git-service.ts:41-43、60-63)
  • Path must be in host's registered workspace list, arbitrary directories cannot trigger git operations; if realpath doesn't exist or isn't in registry, returns workspace-unknown (packages/dsh-git-graph/src/host/git-service.ts:30-43, packages/dsh-git-graph/src/index.ts:30-43)
  • /git/* request body over 1 MiB destroys connection directly, no parsing (packages/dsh-git-graph/src/host/routes.ts:75、90-95)
  • SSE polling every 30 seconds, each subscriber runs one git status; when multiple workspaces subscribe simultaneously, process count = subscriber count; currently no aggregation or sampling (packages/dsh-git-graph/src/host/routes.ts:49、188-206)
  • Single git status timeout 15 seconds (STATUS_TIMEOUT_MS), timeout kills subprocess with AbortController, UI receives timeout error instead of partial result (packages/dsh-git-graph/src/host/routes.ts:58-69、171-186)
  • Branch switching operates at workspace level (git switch affects all sessions), not per-session copy; users wanting to work in parallel on multiple branches need to use "switch workspace" semantics instead of branch capsule (packages/dsh-git-graph/README.zh.md:74 / packages/dsh-git-graph/src/host/git-service.ts:196-203)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/zhu1090093659/dsh-web-ui/packages/dsh-git-graph)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory