dsh-opencode-go-usage

dsh-opencode-go-usage

OpenCode Go plan usage monitor for DeepSeek Harness: a status bar under the chat input in the web GUI showing the 5h-rolling / weekly / monthly quota windows with a live reset countdown. The bar appears only while an OpenCode Go model is active on the current session.

Data comes from the official quota API (GET https://opencode.ai/zen/go/v1/usage, Bearer API key; no workspace id, no cookie).

Install

# From npm (the Web GUI runs on the `web` profile):
dsh plugin --profile web add @cyrilmarin/dsh-opencode-go-usage
# Or from a local checkout:
dsh plugin --profile web add /path/to/dsh-opencode-go-usage
# Upgrade to the latest version:
dsh plugin --profile web update @cyrilmarin/dsh-opencode-go-usage

Restart the profile afterwards (dsh web for the browser UI).

Configure

Recommended: pick the official-channel OpenCode Go provider in Web Settings → Models and enter the API key there; nothing else is needed.

The API key is resolved per refresh through ctx.credentials under the apiKeyEnv reference (default OPENCODE_GO_API_KEY) — it can also be stored manually in ~/.dsh/.credentials.yaml or an environment variable:

- insert:
    - id: opencode-go-usage
      name: '@cyrilmarin/dsh-opencode-go-usage'
      config:
        apiKeyEnv: OPENCODE_GO_API_KEY
        refreshMs: 60000

Field	Type	Default	Meaning
apiKeyEnv	string	OPENCODE_GO_API_KEY	credential reference
apiKey	string	—	direct key fallback (discouraged)
endpoint	string	https://opencode.ai/zen/go/v1/usage	quota endpoint
refreshMs	number	60000	auto-refresh interval
timeoutMs	number	10000	per-request timeout

Usage status bar

A compact, theme-aware status bar rendered in the conversation.composer.dock seat — the band under the chat input window, aligned with the composer column (the same slot the conversation stats line lives in). It reads the session's active model and renders only while the active provider is OpenCode Go (default route opencode-go, configured in Web Settings → Models); on any other provider — or before a model selection is known — it contributes zero layout.

• One threshold-colored chip per quota window (5h Rolling / Weekly / Monthly): colored dot + used percent (green <60% / orange ≥60% / red ≥85%), with the 5h-rolling window's exact reset countdown (↻3h25m).
• A live health dot, the sample age ("Updated 2m ago"), a quiet "refresh failed, showing previous data" note, and a manual refresh affordance (↻).
• Unconfigured/error details render on hover (title); a failed fetch never blanks the bar.

Display stability

Data and health are decoupled: when a refresh fails (timeout, API error), the bar keeps showing the last successful sample — the status dot turns yellow and a quiet "refresh failed, showing previous data" note appears. The display is never blanked; error / unconfigured states appear only before the first successful fetch.

The status dot reuses the shared dsh-client-ui-primitives StateDot so the bar's affordances stay visually consistent with the rest of DSH.

Internationalization

The status bar is fully bilingual (简体中文 / English). The active language follows dsh's own locale.preference in the host settings ($DSH_HOME/settings.yaml, namespace locale); when no explicit preference is set, the browser's language is used as a fallback, exactly like the rest of the Web UI. Switching the language in Web Settings → General → Language re-renders the bar immediately — no reload, no refresh.

All copy lives in the plugin's locale namespace (opencode-usage, zh/en dictionaries registered through ctx.locale); window names, countdowns, relative timestamps, accessibility labels, and the host-reported failure messages are covered. Host errors are sent to the browser as stable machine codes (connect, timeout, unauthorized, http, parse, no-data, unconfigured), and the client localizes them — one translation source, no language logic on the host.

Model Experience

Request surface and condition

The plugin exposes no model-facing surface: the model never sees quota values, no prompt text or tool schema is added.

Token effect

None — no model request, no injected tokens.

KV Cache effect

None — no request tokens added or replaced.

Known Limitations and Deferred Work

• Poll latency — the status bar polls every 60s; quota changes appear within at most one poll cycle (the manual ↻ refresh is instant).
• Data freshness — after repeated failed refreshes the bar keeps showing the last successful sample, which grows stale until a refresh succeeds.
• Model gating source — the bar shows while the session's model selection (read from the shared per-session model directory) reports the opencode-go provider; before the first selection load or on any other provider it stays hidden.
• Single account — one API key per profile; multi-account dashboards are out of scope.