dsh-hud

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 10 commits (commitCount, 1–50; the commit list starts collapsed)
• Change-driven folding (2026-09-26) — a clean repo/sub-repo collapses to a single line (with ✓ and ↑↓ unpushed counts); a dirty one auto-expands down to the file level. Once you toggle a repo yourself, your choice wins and is remembered (localStorage)
• 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 0.1.7 and later:
dsh plugin --profile web add "github:a903067276-rgb/dsh-hud#main"
# DSH 0.1.5 and older (this release needs 0.1.7+):
# dsh plugin --profile web add "github:a903067276-rgb/dsh-hud#v1.4.1"

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):
  • ✅ DSH 0.1.7 and later — use this release (v1.8.1): it declares peerDependencies: {"@deepseek-ai/dsh": "^0.1.7-rc.1 || ^0.2.0-rc.1"}, so a mismatched host refuses to load it with an explicit reason instead of failing quietly. Settings move to the 0.1.7 model (plugin Config, live-editable .volatile() fields), so changes apply without a restart.
  • ✅ DSH 0.2.0-rc.1 — verified compatible: the peer range now covers both lines (^0.1.7-rc.1 || ^0.2.0-rc.1) and dsh.compatibility.dshReleases adds "0.2.0-rc.1": "compatible" — verified on a real 0.2.0-rc.1 host and a shadow instance. Since 0.2 the host gates profile bundles on peer compatibility and skips the whole bundle when the declared range misses the running host, so this range is what keeps the plugin loading.
  • ⚠️ DSH 0.1.5 and older — install the previous tag v1.4.1: that line keeps the old behavior and uses no 0.1.7-only API.
  • ⛔ Old plugin releases (up to v1.4.1) are not supported on 0.1.7 — every git command fails (shell.run is gone) so the Git block is empty, and the right-sidebar tab form is never used. Upgrade the plugin together with the host.
• 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 balance request: balanceMode picks off (never request, never show) / official (default, DeepSeek GET /user/balance with the DEEPSEEK_API_KEY credential) / custom (your own endpoint — balanceUrl plus optional balanceHeader (default authorization: Bearer <key>), balanceTokenEnv (default DEEPSEEK_API_KEY), balancePath (e.g. data.balance) and balanceCurrency). The key is only ever sent to the address you configured yourself; anything unavailable shows -- instead of a guessed number.
• Presets (balancePreset): kimi / siliconflow / openrouter (total_credits − total_usage) / zai / one-api (needs balanceScale, e.g. 500000 per unit, plus your own balanceUrl) / deepseek. Fields you set yourself always win over the preset. Custom URLs must be https (localhost/LAN excepted), redirects are never followed (so Authorization can't be bounced to another host), the key only ever travels in a header, and a 200 response that yields no number gets a one-time hint.
• 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