Preface¶

When using DeepSeek Harness (DSH) to run dsh web, checking the balance and token usage typically requires switching to another page or terminal. This becomes even more challenging when multiple providers and channels (DSH and Claude Code) are running in parallel, making it difficult to see at a glance “how much was spent today” or “which channel is the primary consumer.”

dsh-usage is a community-maintained client-side plugin that attaches a persistent dock to the bottom-left corner of the Web GUI, providing a customizable balance/usage panel. Data is aggregated locally, and credentials are parsed on the Harness server side without entering the browser response.

What This Is¶

dsh-usage (GitHub: Aisland-SJL/dsh-usage, SkillHub directory: Aisland-SJL/dsh-usage) is maintained by Aisland-SJL, classified as a client-side plugin, and licensed under MIT. The current version is 0.2.0, with approximately 20 stars on GitHub.

It is designed for DSH users who have enabled the web profile and addresses three needs: a constantly visible balance and usage summary, a draggable and sortable detail panel, and a usage comparison between DSH channels and Claude Code channels.

Core Features¶

Persistent Dock¶

Key numbers are displayed permanently in the bottom-left corner of the interface. When the balance is sufficient, it shows green; when depleted, it turns red. Today’s/monthly tokens, and cache hit rates are displayed in a compact row. A settings gear and a one-click refresh button are located in the corner. When the sidebar is collapsed, the dock shrinks into a small balance capsule.

Detail Panel (Seven Components)¶

A two-column card layout where each component can expand details, collapse, hide, pin, and supports drag-and-drop reordering:

Appearance and Layout Customization¶

Accent color (preset + color picker), background color, and panel transparency can be adjusted in real time. The component states (pin/collapse/hide/drag-reorder) are written to localStorage and preserved after refresh.

Dual-Channel Usage Comparison¶

On the DSH side, token data comes from the Harness built-in statistics. On the Claude Code side, it aggregates via incremental parsing of JSONL logs under ~/.claude/projects, retaining only numbers and not reading message content.

Local-First and Security Boundaries¶

The plugin exposes three GET endpoints accessible only via loopback. Credentials are parsed server-side from ~/.dsh/.credentials.yaml via the Harness credentials seam; the plugin does not read, cache, or echo keys. Upstream balance queries enforce HTTPS, perform DNS pre-resolution, reject private/loopback addresses, bind connections to verified IPs (to prevent DNS rebinding), set a response limit of 1 MiB, and have a 15-second timeout. Usage cache is written to ~/.dsh/storages/, storing only aggregated numbers and fold cursors.

Supported Balance Providers¶

Providers without a public balance interface will display a clear status without guessing values. The interface supports Chinese and English.

Installation and Enabling¶

Prerequisites: @deepseek-ai/dsh >= 0.1.0-rc.6 and using the web profile.

The following commands are from the plugin README and SkillHub directory page:

dsh plugin --profile web add "github:Aisland-SJL/dsh-usage"

After installation, restart dsh web, perform a hard refresh in the browser, and the dock should appear in the bottom-left corner. For updates and uninstallation:

dsh plugin --profile web update dsh-usage
dsh plugin --profile web remove dsh-usage

Typical Usage¶

Configuring Credentials¶

Balance queries read references from ~/.dsh/.credentials.yaml. Fill them in according to the provider in use:

DEEPSEEK_API_KEY: sk-your-key-here            # Official DeepSeek line
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-...       # OpenRouter account (Management Key, not inference key)
ZAI_API_KEY: your-zai-key                     # Z.ai Open Platform

If Moonshot/Kimi is already configured in llm-pi-ai, the corresponding apiKeyEnv will be auto-discovered.

Panel Operations¶

1. Click the gear icon in the dock corner to open the detail panel.
2. Switch providers in the Balance component to view itemized balances.
3. Click ↻ or wait for background refresh (once at startup, then every 5 minutes): balance, DSH tokens, and Claude Code aggregation update synchronously.
4. In the Usage log, click on a specific day to drill down to per-model details.
5. In the customizer, adjust accent color, background, transparency, drag component order, and pin frequently used items.

HTTP API (For Local Debugging Only)¶

Non-GET requests return 405; non-loopback calls return 403. Responses are JSON with Cache-Control: no-cache. Do not expose these endpoints to the LAN or public network via reverse proxies.

Use Cases and Notes¶

Suitable for:

• Users who keep dsh web open long-term and need to check balance and daily/monthly usage at any time;
• Users who use both DSH and Claude Code and want to compare token consumption between the two channels;
• Users concerned about privacy who prefer local aggregation of usage and keeping keys out of the browser.

Pre-installation notes:

• The plugin runs with the current dsh process permissions. You should review the source code and MIT license before installation.
• Claude Code aggregation depends on local ~/.claude/projects logs; when no logs are present, the corresponding channel shows as empty or zero, which is expected behavior.
• OpenRouter balance requires a Management Key; a standard inference key cannot query credits.
• SkillHub is a community directory site and has no official affiliation with DeepSeek / High-Flyer; the plugin is also part of the community ecosystem, following DSH’s “everything is a plugin” extension approach.

Conclusion¶

dsh-usage consolidates balance, token usage, cache hit rates, activity heatmaps, and dual-channel comparison into the bottom-left corner of the Web GUI. Configuration and layout are locally persistent, while credentials and upstream queries remain within the server boundary. If you are already using DSH with the web profile, you can install it using the commands above, restart, and perform a hard refresh to verify.

• SkillHub Directory: https://www.skillhub.cn/plugins/Aisland-SJL/dsh-usage
• GitHub Repository: https://github.com/Aisland-SJL/dsh-usage