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.

Screenshot

The gauge button in the input toolbar opens the floating panel showing git status, commit history, MCP servers, skills and official usage info (tokens, cache hit rate, turns/steps, LLM & tool time, 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).

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