dsh-opencode-usage

OpenCode Go plan usage display for the DSH web GUI — a persistent badge under the composer shows rolling / weekly / monthly usage percents and reset countdowns; click to expand a card; agents can query the balance via the opencode_go_usage tool.

Official DSH bundle plugin. Install with one command:

dsh plugin --profile web add github:vinyumao/dsh-opencode-usage#<ref>

English | 中文

Capability surface

How it works

Usage comes from the OpenCode Go subscription quota endpoint:

GET https://opencode.ai/zen/go/v1/usage
Authorization: Bearer <API_KEY>     # the regular Anthropic-compatible API key

Example response:

{
  "usage": {
    "rolling": { "status": "ok", "percent": 0, "resetsAt": "2026-…Z" },
    "weekly":  { "status": "ok", "percent": 0, "resetsAt": "2026-…Z" },
    "monthly": { "status": "ok", "percent": 0, "resetsAt": "2026-…Z" }
  }
}

⚠️ Unverified: this endpoint is not part of the official public documentation — it was surfaced by the cc-switch community (issue includes a verification script). The response shape may change as opencode evolves; this plugin parses defensively (both usage.-prefixed and bare windows, both resetsAt and numeric resetsInSeconds forms), so please defer to the live response if the structure changes.

The browser never talks to the upstream directly: every request goes through the host process's /api/dsh-opencode-usage/* routes (same-origin fetch), so the API key never enters the browser.

About OpenCode Zen

This plugin is Go-plan specific — it shows the subscription quota windows, which only exist for OpenCode Go. OpenCode Zen is a separate pay-as-you-go gateway (prepaid balance, per-token billing) and has no equivalent API-key-authenticated balance endpoint: the official feature request (anomalyco/opencode#10448, "Add Zen balance API endpoint") is still open, and community tools that show Zen balances rely on brittle browser-cookie scraping of the workspace billing page (e.g. CodexBar). If a public Zen balance API ships, this plugin can add a plan option to consume it.

Installation

Zero runtime SDK imports: the host half imports no @deepseek-ai/* packages at runtime — the agent tool is written in the raw registrable shape ctx.tools.register accepts (standard JSON Schema in output.schema, plain render/execute), instead of being built with defineTool from @deepseek-ai/dsh-tools. That is what makes a git vendoring install (dsh plugin add github:..., which clones into a workspace vendor/ dir) work out of the box: Node never has to resolve @deepseek-ai/* from the plugin's own node_modules, because the plugin never imports them. (Earlier revisions imported defineTool; if you hit ERR_MODULE_NOT_FOUND for @deepseek-ai/dsh-tools, update to the latest ref.)

Method 1: one dsh plugin command (recommended)

From anywhere:

dsh plugin --profile web add github:vinyumao/dsh-opencode-usage#<ref>

package.json declares dsh.bundle.patch, so the install automatically joins the profile's dsh.profile.bundles layer stack and mounts cordis.patch.yml. Then restart dsh web — the badge appears under the composer.

A git install fetches source; this plugin is pure source (index.mjs / client.js, no build step), so it works right away with no prepare script. If pnpm asks for an allowBuilds permission, copy the package key it prints into the profile's pnpm-workspace.yaml and retry. For reproducible installs, pin <ref> to a commit SHA (#<sha>).

Method 2: manual wiring

1. Add to the profile's package.json dependencies:

   "@chen-001/dsh-opencode-usage": "github:vinyumao/dsh-opencode-usage#<ref>"
   

2. Run pnpm install in the profile directory.
3. Confirm dsh.profile.bundles contains the package (dsh plugin reconciles automatically); or add to the profile's cordis.patch.yml:

   - insert:
       - id: opencode-usage
         name: '@chen-001/dsh-opencode-usage'
   

4. Restart dsh web — the badge appears under the composer.

Installation guide for AI agents

When an AI assistant installs this on the user's behalf, follow these steps:

1. Confirm the dsh CLI: dsh --version. In a source checkout, use pnpm dsh ... instead.
2. Install (pin <ref> to the latest commit SHA):

   dsh plugin --profile web add github:vinyumao/dsh-opencode-usage#<ref>
   

   • First use initializes the profile (auto-bundles @deepseek-ai/dsh-base).
   • If pnpm refuses to run a git dependency's prepare script, add the printed package key to allowBuilds in $DSH_HOME/profiles/web/pnpm-workspace.yaml and re-run.
3. Verify the layer stack: dsh --profile web --dump-config should show a # == @chen-001/dsh-opencode-usage layer (with the opencode-usage row).
4. Restart web: quit the running dsh web process and start it again.
5. Smoke test: open the DSH web GUI — the OpenCode Go：… badge should appear under the composer; ask the agent to run the opencode_go_usage tool, which should return the three windows.
6. Troubleshooting: if the badge shows "query failed", check whether OPENCODE_GO_API_KEY is set, or click the badge and fill in the API key in the config form.

Uninstall

The same dsh plugin command that installed it removes it: it runs pnpm remove in the profile directory and automatically drops the plugin from the dsh.profile.bundles layer stack (so no manual cordis.patch.yml / bundles editing is needed):

dsh plugin --profile web remove @chen-001/dsh-opencode-usage

Then restart dsh web — the badge disappears, and the /api/dsh-opencode-usage/* routes, the opencode_go_usage tool, and the agent announcement are unloaded.

Optional cleanup

• Config file: the API key is stored in plaintext at ~/.dsh/dsh-opencode-usage.json (mode 0600). If you do not plan to reinstall, delete it: rm ~/.dsh/dsh-opencode-usage.json. (The key may also be referenced by the DSH opencode-go model provider through the OPENCODE_GO_API_KEY environment variable — that configuration is independent of this plugin.)
• allowBuilds entry: if the install required adding the printed package key to the profile's pnpm-workspace.yaml allowBuilds, that entry can be removed as well.

Manual fallback

If dsh plugin is unavailable, remove the dependency and the bundle row by hand in the profile directory (~/.dsh/profiles/web):

1. pnpm remove @chen-001/dsh-opencode-usage
2. Delete the "@chen-001/dsh-opencode-usage" row from dsh.profile.bundles in package.json
3. Restart dsh web

Verify

• dsh --profile web --dump-config should no longer list a # == @chen-001/dsh-opencode-usage layer.
• After the restart, the OpenCode Go：… badge is gone.

Configuration

API key resolution order: plugin config file → OPENCODE_GO_API_KEY environment variable → none.

Optional file-based config:

// ~/.dsh/dsh-opencode-usage.json
{ "apiKey": "sk-…", "baseUrl": "https://opencode.ai/zen/go", "refreshSeconds": 300, "webUsageUrl": "https://opencode.ai/workspace/<workspace-id>/go" }

Agent tool

opencode_go_usage (no arguments) returns:

OpenCode Go 用量（https://opencode.ai/zen/go）
滚动用量：0%，重置于 3 小时 20 分钟
每周用量：0%，重置于 2 天 9 小时
每月用量：0%，重置于 30 天 22 小时
抓取时间：…

Security

• /api/dsh-opencode-usage/* is loopback-only (with same-origin checks); a LAN-exposed deployment cannot leak the proxied key.
• The API key is stored in plaintext at ~/.dsh/dsh-opencode-usage.json (0600) — the same trust model as the dsh-ssh credential store.
• The config read endpoint only returns hasApiKey / apiKeySource; the key itself never leaves the host.

Plugin management

Manage installed plugins with the plugin-registry console (a browser panel): manage the profile plugin install state (bundle layer stack + insert rows + enable/disable) without hand-editing config. Install:

dsh plugin --profile web add github:vlln/plugin-registry/packages/plugin/console

Development

node tests/sanity.mjs   # pure-logic checks (parse/format/config store), no dsh runtime needed
node tests/routes.mjs   # route-layer integration (loopback fence/method guards/JSON bodies)

Known limitations

• The badge hangs in the composer dock (visible when a session is open); it is hidden when no session is active.
• The usage endpoint is not officially documented; the shape may change (see "How it works").
• The config form's key input is "append/overwrite" semantics: saving with an empty key keeps the current key; to fall back to the environment variable, edit the config file and remove the apiKey field.

License

MIT