dsh-claude-usage
English | 简体中文
A polished Anthropic Claude plan-usage indicator for the DeepSeek Harness Web UI.
The plugin preserves the standard Settings gear and label while adding a context-meter-style ring at the far right. The ring contains the Anthropic mark and opens a detailed quota panel on hover or keyboard focus.
Features
- Native-looking usage ring using the same 28 px geometry and DSH design tokens as the conversation context meter.
- Full quota detail for Claude plan limits: the 5-hour session window, the weekly window, model-scoped weekly limits, extra-usage state, plan and rate-limit tier.
- Five-minute polling by default, configurable through the bundle row.
- Fresh-on-hover data with a 250 ms debounce, one in-flight request, a shared five-minute poll cache, a shorter forced-hover cache, and failure throttling.
- Honors Anthropic's
Retry-After cooldowns; the usage endpoint itself rate-limits aggressive polling.
- Last-good fallback so a temporary provider or network failure does not erase useful data.
- Read-only credential access: the plugin never writes to or refreshes Claude Code's stored sign-in.
- Loopback-only API route and an allowlist normalizer that removes tokens, identifiers, emails, and unknown provider fields.
Requirements
- Node.js 20 or newer
- pnpm 10
- DeepSeek Harness 0.1.1-rc.2 or compatible
- A recent Claude Code CLI signed in with a Claude subscription (
claude login); until Claude Code holds a valid sign-in, the indicator shows an error state pointing at claude login
- Windows or Linux, where Claude Code stores its OAuth credentials at
~/.claude/.credentials.json (macOS keeps credentials in the Keychain and is not supported yet)
Install from this checkout
Build the package:
pnpm install
pnpm run check
Add it to a DSH profile from this directory:
dsh plugin --profile web add .
dsh --profile web --dump-config
dsh web
During development, Host changes hot-reload only while pnpm run dev is running and rebuilding the plugin output. Browser client changes require a rebuild and then a refresh of the existing Web page. The client bundle is loaded by DSH's client-module system; a separate Vite server is neither required nor useful.
Remove it with:
dsh plugin --profile web remove dsh-claude-usage
Install a packed artifact
A tarball ships prebuilt Host and lazy-CJS client artifacts, avoiding install-time build approval:
pnpm pack
dsh plugin --profile web add ./dsh-claude-usage-0.1.3.tgz
For a Git-host install, pnpm 10 requires the profile to allow this package's prepare script. Pin a commit and follow the exact allowBuilds instruction printed by DSH/pnpm.
Configuration
All four fields are available in Settings → Plugins → Claude usage. Changes are staged locally until Save, are persisted through DSH Settings, and the saved settings/profile patches apply live without a restart. The profile row remains the base configuration beneath saved user overrides.
The bundle inserts this row:
- id: claude-usage
name: dsh-claude-usage
config:
refreshIntervalMs: 300000
hoverRefreshMinAgeMs: 30000
requestTimeoutMs: 15000
credentialsFile: ''
Override the whole row in the profile's cordis.patch.yml to change the composition-layer base. Later layers replace a row's complete config value; saved Settings UI values override that base.
| Field | Default | Meaning |
|---|
| refreshIntervalMs | 300000 | Background poll interval; minimum 60 seconds. |
| hoverRefreshMinAgeMs | 30000 | Minimum age before another hover refresh; minimum 5 seconds. |
| requestTimeoutMs | 15000 | Timeout for each Anthropic usage request. |
| credentialsFile | (empty) | Optional absolute path to the Claude Code credentials file; empty selects the default per-OS location. |
How it works
- The Host plugin injects DSH's webServer service and registers GET /api/plugins/claude-usage.
- On each read it performs a read-only lookup of the Claude Code OAuth access token in the credentials file.
- It calls Anthropic's OAuth usage endpoint — the same undocumented beta API behind Claude Code's /usage command — with the
oauth-2025-04-20 beta header.
- A strict normalizer returns quota-only data (percentages, ISO reset times, extra-usage flags) to the loopback browser route.
- The browser registers an independent action in sidebar.footer.action, reserves space at the right edge of the Settings row, and leaves the built-in Settings button and its behavior untouched.
- The browser polls on the configured cadence and requests a coalesced refresh after a 250 ms hover debounce.
Expired tokens are detected locally and surface a "run claude login" error state instead of hammering the endpoint; Claude Code refreshes its own sign-in during normal use. A 429 response arms a Retry-After-aware cooldown so background polls never fight Anthropic's rate limiter.
The client artifact is not ordinary browser ESM. tsdown.config.ts emits DSH's required lazy-CJS registration. React and DSH UI packages remain external and resolve through DSH's client module table, preventing duplicate React runtimes.
Security and privacy
- The plugin reads the credentials file but never stores, transmits, logs, or refreshes the token; the access token exists only inside the Host process for the duration of one request.
- The Web route accepts only GET from loopback clients and rejects cross-site Origin, Referer, and Fetch Metadata signals.
- Responses omit tokens, account/workspace/user IDs, emails, raw provider payloads, and unknown fields; only clamped percentages, reset timestamps, labels, and boolean flags survive normalization.
- Error messages are static strings that never echo credential paths or provider responses.
- The provider route is not configurable beyond the optional local credentials path, avoiding an arbitrary authenticated proxy.
Development
pnpm run typecheck
pnpm run test
pnpm run build
pnpm run pack:check
The default suite skips the live provider test. Run it when Claude Code is installed and signed in:
$env:CLAUDE_LIVE = '1'
pnpm exec vitest run tests/claude-live.spec.ts
References
License
MIT
