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

1. The Host plugin injects DSH's webServer service and registers GET /api/plugins/claude-usage.
2. On each read it performs a read-only lookup of the Claude Code OAuth access token in the credentials file.
3. 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.
4. A strict normalizer returns quota-only data (percentages, ISO reset times, extra-usage flags) to the loopback browser route.
5. 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.
6. 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

• DSH: Your first plugin
• DSH: Package and install
• DSH: Adding a settings card
• DSH: Client modules
• ccusage — local transcript analytics for Claude Code
• Community confirmations of the OAuth usage contract: LimitsChecker, claude-usage-widget

License

MIT