dsh-hud 📊

English | 简体中文

A HUD status panel plugin for DeepSeek Harness (dsh) web: one button in the input toolbar opens a floating panel with git status, MCP servers, skills, official usage info and balance.

Unofficial project: independently developed and maintained by a community member, not an official DeepSeek product.

Screenshots

Default form: a tab in the official right sidebar (DSH 0.1.5+), toggled by the HUD button left of the composer — clicking it again collapses the sidebar. It can also run as a floating panel (older hosts fall back automatically) with drag-resizable position and width. The panel shows git status, commit history, watched repos, MCP servers, skills and official usage info (tokens in/out, cache hit rate, per-model breakdown, context usage).

Features

• Git — branch, ahead/behind, unstaged / staged / untracked files (collapsible groups), per-file +N/-N summaries, click a file to expand its full diff, last 5 commits
• MCP — connected MCP servers (derived from mcp__<server>__<tool> tool names)
• Skills — skills available to the current agent
• Official info — current model + reasoning effort, plan mode state, token usage (input / output / cache-hit rate), session stats (turns, steps, LLM & tool time, decode tok/s, context usage %)
• Balance — official DeepSeek account balance, auto-fetched from GET /user/balance using the DEEPSEEK_API_KEY credential (the key never leaves the host; shows -- when unavailable)
• Per-model usage — current session's token buckets broken down by model (requests, input, cache, output), so flash/pro usage both remain visible after switching

The button also shows a live badge with the number of uncommitted files, so you can see at a glance that a project has pending changes without opening the panel.

Install

This repository is an official bundle plugin (dsh.bundle + dsh.client in the root package.json), installed through the official profile manager:

dsh plugin --profile web add "github:a903067276-rgb/dsh-hud#main"

Then restart dsh web (bundle layers are composed at startup; HMR does not apply). Requires pnpm on PATH (dsh plugin forwards to pnpm).

Manual mount fallback: see docs/install.md.

Usage

Click the gauge icon in the input toolbar (official DSH design tokens, follows dark/light theme). The panel opens on the left side by default (240px wide), clear of the official right-edge turn navigator; drag its title bar to move it anywhere (position remembered in localStorage, restored on reopen); drag its left edge to resize (200–480px, remembered in localStorage). Section headers with count badges are clickable to collapse/expand. Data auto-refreshes every 30s (when the panel is closed, only the lightweight git badge keeps polling).

Platform support

Platform	Status
macOS	✅ Fully tested (development environment)
Linux	⚠️ Not yet tested — expected to work, see docs/install.md
Windows	⚠️ Not yet tested — expected to work, see docs/install.md

Requirements

• DSH web >= 0.1.1-rc.1 (run with npx @deepseek-ai/dsh web)
• Version compatibility (the per-model usage projection uses the DSH 0.1.1+ contract; 0.1.0-rc.7/rc.8 still use the old one):
• Maintenance policy: this plugin keeps evolving with the latest DSH releases; compatibility with older DSH versions is best-effort only and not guaranteed going forward.

Your DSH version	Install this	Note
0.1.1-rc.1 and newer	main (v1.2.15+)	Full features
0.1.0-rc.7 – 0.1.0-rc.8	v1.2.11 — dsh plugin add github:a903067276-rgb/dsh-hud#v1.2.11	Last release with the pre-0.1.1 projection contract
0.1.0-rc.6 and older	rc6-compat — dsh plugin add github:a903067276-rgb/dsh-hud#rc6-compat	Frozen, no maintenance — upgrade recommended

• git CLI on PATH
• No extra shell needed: DSH's shell service executes everything via bash -c on all platforms (Git Bash on Windows), so if DSH runs, this plugin runs.

How it works

┌─ Host (Node, cordis plugin) ──────┐      ┌─ Browser (client bundle) ──┐
│  lib/index.js                     │      │  lib/client.js             │
│                                   │      │                            │
│  webServer.register(/api/dsh-hud) │──fetch──▶  input.left seat: button │
│    ├ /api/dsh-hud   git/mcp/...   │      │  shell.overlay seat: panel  │
│    └ /api/dsh-hud/diff  per-file  │      │                            │
└───────────────────────────────────┘      └────────────────────────────┘

The host serves JSON over the webServer prefix route and runs all git commands in a single bash -c call with __HUD_[BHSLN]__ segment markers (fast project switches). The client is a hand-written window.__ModuleLoader__.load(...) bundle with zero build step, sharing state between the button and the panel through a module-level store (useSyncExternalStore). Details and known pitfalls for maintainers: docs/architecture.md.

Notes

• Use either the official bundle install or the manual mount — never both.
• All data is gathered locally from the running dsh instance; the only outbound call is the official balance API using the DEEPSEEK_API_KEY credential (the key never leaves the host).
• DSH_HUD_NO_WATCH=1 disables file watching entirely — the HUD then refreshes purely via its 30s polling + manual/focus refresh. Useful on machines with enormous directory trees (e.g. a parent folder containing dozens of repos) where macOS file watchers are unreliable; the watcher is also capped at 128 by default (deeper changes surface via polling within ~30s).
• DSH_HUD_BALANCE=off disables the balance request entirely — no outbound call, no log line, the panel just shows --.
• Balance only works with an official DeepSeek key. The endpoint (/user/balance) is the official one and the credential is DEEPSEEK_API_KEY; if that variable holds a relay/gateway key, the request returns 401, so the panel shows --. Such a failure is reported once and then backed off for 30 minutes (older versions retried every 60s and logged every attempt). Support for non-official API balances is planned (#10).

Development

lib/index.js        host half — data routes (git / mcp / skills / model)
lib/client.js       client half — UI (button + panel), final bundle, no build step
cordis.patch.yml    bundle patch — single package-name mount (official bundle flow)
docs/               install guide & architecture notes
examples/           manual double-mount example (fallback install path)

To test locally: symlink (or dsh plugin --profile web link) into the web profile's node_modules, add the two mount entries, restart dsh web.

Design philosophy

Simple by design. dsh-hud is deliberately minimal:

• Zero dependencies — no runtime packages, no build step; the client bundle is the final artifact in the repo
• Read-only — it only reads git status, MCP/skills listings and official projections; no git write operations, no file mutations
• One button, one panel — no settings pages, no config files

It is an independent community project: not an official DeepSeek product, and not affiliated with, forked from, or sharing code with any other DSH plugin project. If your workflow needs heavyweight SCM operations (commit/push UI, file trees, git graphs), other plugins cover that; dsh-hud deliberately stays a glanceable status HUD and coexists with them.

Community

This is a plugin for DeepSeek Harness. Find more plugins via the dsh-plugin topic.

License

MIT