Introduction

The philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” During session development, frequently checking branch status, ahead/behind counts, and switching branches usually requires manually running Git commands. The dsh-git-status plugin integrates Git status into the session view through official slots, displays real-time status in the session header badge and the input-area environment line, and provides branch switching to reduce context-switching costs.

Install and Enable

To install this plugin, use the official package management command and specify version v0.1.0.

dsh plugin --profile web add github:shenhuanageshei/dsh-git-status#v0.1.0

After installation, the plugin is automatically mounted into the designated slots of the session view. For non-Git sessions, both displays are automatically hidden.

Core Features

This plugin mainly provides the following capabilities:

  1. Real-time status display: Displays the Git status of the current working directory in the session header badge and the input-area environment line, including branch name, ahead/behind counts, dirty working tree count, worktree status, HEAD commit information, and relative time.
  2. Branch switching and creation: Clicking the session header badge opens a branch menu that supports searching, switching branches, and creating new branches. New branch creation supports remote DWIM (Do What I Mean) tracking-branch logic.
  3. Security model: Write operations use only git switch (never --force), and are protected by a ref whitelist, shell-free spawn argument arrays, and check-ref-format validation for new branch names to maintain security. When the working tree has uncommitted changes, the plugin rejects switch operations that could cause data loss.
  4. Smart interaction: Supports per-cwd mutex locks for serialized switching, and requires secondary confirmation when switching while an agent is running. Read commands include the --no-optional-locks parameter to avoid contending for the Git index lock with agent operations.

UI and Interaction

The plugin’s interface design consists of two main areas:

  • Session header badge: Formatted as ⎇ branch-name ▾.
    • Clicking it opens a branch menu with search and operation support.
    • When the working tree has uncommitted changes, the badge displays an amber dot to indicate this.
    • When in a detached HEAD state, it displays as ⎇ @short-sha.
    • When a linked worktree exists, it displays the ⧉ marker.
  • Input-area environment line: Located below the input card, occupying the same slot as the official statistics line but serving as an ambient readout line.
    • Example format: ⎇ main ↑2↓1 · +3 ~2 ?1 · ⧉ wt:feature-x · 0a1b2c3 10m ago.
    • Segmented coloring (⎇ brand blue, branch name primary, dirty status amber, worktree purple, HEAD muted gray), 13px font size, 14px segment spacing, and a spacious feel.
    • Hovering reveals cwd, primary repository, HEAD, upstream, and worktree lists.

Security Model

The plugin’s write operations follow strict security constraints:

  • No force: Uses only git switch and does not use --force. If dirty changes could be lost, Git itself rejects the operation and displays the original error message.
  • Ref validation: New branch names must pass check-ref-format validation, and switch targets are limited to enumerated refs in a whitelist.
  • Concurrency control: Uses per-cwd mutex locks to serialize switching and invalidates caches after a successful switch.
  • Lock contention: Read commands include --no-optional-locks, avoiding contention over the Git index lock with agent operations.

Architecture

The plugin uses a zero-build “Node half + Client half” architecture:

  • Node half (lib/index.mjs): Provides HTTP API routes, including GET /status (polling cache with 1.5s TTL), GET /branches (5s TTL), and POST /switch. The session context is obtained through ctx.sessions.get(id).header.cwd.
  • Client half (lib/client.js): Mounted into official slots through ctx.slots.inject. The client is responsible for UI rendering. Polling starts at 2s, adapts to slow repositories with backoff up to 8s, and pauses when the page is hidden.
  • Zero build: The client-side code is hand-written CJS, wrapped with __ModuleLoader__, and structurally aligned with task-status build output, so changes take effect immediately.

Development

To debug or modify the plugin locally:

  1. Inject: Takes effect at runtime without a restart.
    dev_inject_plugin <本仓库克隆目录>
  1. Reload: Run after modifying the Node half. The Client half requires a page refresh.
    dev_reload_package dsh-git-status
  1. Uninstall:
    dev_uninject_plugin dsh-git-status

Notes

This plugin runs with the permissions of the current DSH process. Before installation, review the source code and license (MIT). This plugin is maintained by a community developer and has no affiliation with DeepSeek or the official app store.

Summary

By embedding Git status and operations directly into the DSH session interface, dsh-git-status enables a shift from “external command line” to “in-UI integration.” Its zero-build architecture and strict security model make it suitable for direct use in development workflows.