Introduction¶

When running tasks for long periods in the DSH Web GUI, users generally don’t care about the model vendor name; they only care about two things: how much quota is left and when it resets. The OpenCode GO plan splits the quota into three windows: 5 hours, weekly, and monthly, but the official interface only shows percentages on the web page, not in scripts or the GUI dashboard. The plugin introduced below turns the usage of these three windows into pills below the input box. Clicking them reveals the exact amount and countdowns for each window, eliminating the need to switch windows or write scripts yourself.

The plugin is maintained by zyhnbyyds, and the repository is zyhnbyyds/dsh-opencode-go-usage. It is positioned as a DSH client plugin that adds a usage display and API Key settings page below the conversation composer. We will cover the features first, followed by installation, usage, and notes.

Core Features¶

1. Pills appear below the input box, formatted like Go · 5h 7% · 周 7% · 月 3%. The prefix is the plan name, followed by the used percentage of the three quota windows in sequence. The spacing is compressed by the built-in stats bar.

2. Clicking the pill pops up a details card above the indicator bar: the header contains the icon, plan name, and used/limit for the current month. A separator line is followed by three rows of data, each containing a percentage and a reset countdown. The footer shows the update time, plan name, and expiration/renewal status. The card header includes a refresh button ↻.

3. When there is no readable API Key, the pill displays Go · Set Key. Clicking it prompts you to go to the settings page to fill it in and will not cause a white screen or disappearance.

4. The settings page supports saving, clearing, and re-reading the Key. It also displays the current credential source in real-time (Plugin Settings / DSH Credentials / Environment Variables / auth.json). When a Key is invalid, it shows “Current reading: …”.

5. The Host side is pure Node ESM, and the Client side is a hand-written lazy-loaded bundle with zero runtime dependencies. The styles rely solely on --dsw-alias-* theme variables and follow the light/dark mode.

Installation & Enablement¶

DSH version 0.2.1 or higher is required. The README confirms this has been tested successfully on 0.2.1-rc.3. The npm package name is @zgyh/dsh-opencode-go-usage.

Method A: Install from npm (Recommended):

dsh plugin --profile <your profile> add @zgyh/dsh-opencode-go-usage

Method B: Install from git source:

dsh plugin --profile <your profile> add github:zyhnbyyds/dsh-opencode-go-usage

Method C: Local directory: First clone the repository locally, then install from that directory in DSH’s “Settings → Plugins”. The bundle name is @zgyh/dsh-opencode-go-usage; alternatively, you can have the agent point the plugin manager’s install_bundle to that directory. Plugin injection happens automatically via cordis.patch.yml (dsh.bundle.patch), so you don’t need to manually edit the profile.

After installation, refresh the DSH page.

Typical Usage¶

After installation, open any session, and usage pills will appear below the input box. To switch accounts or top up quota, go to “Settings → OpenCode GO Usage”:

1. Enter oc_sk_… and click “Save”. This writes the plugin-specific OPENCODE_GO_USAGE_API_KEY to the Harness credential service. Usage is re-read immediately after saving.

2. Click “Clear Saved Key” to delete the plugin-specific credential. Usage reading falls back to the fallback chain of DSH model credentials / environment variables / auth.json.

3. The parsing order for the Key is: OPENCODE_GO_USAGE_API_KEY saved in the settings page → OPENCODE_GO_API_KEY in the Harness credential service → Process environment variable OPENCODE_GO_API_KEY → OpenCode’s auth.json (i.e., ~/.local/share/opencode/auth.json or ~/.config/opencode/auth.json).

Note that the Key filled in the settings page is only for usage display. DSH calls the model using the Key from “Settings → Models”. The two can be different accounts. If the two Keys belong to different accounts, the interface displays the usage corresponding to the account associated with the settings page Key.

If you need to adjust the quota or refresh frequency, you can override the config line in the user layer of the profile’s cordis.patch.yml:

- id: opencode-go-usage
  config:
    credential: OPENCODE_GO_API_KEY
    settingsRef: OPENCODE_GO_USAGE_API_KEY
    baseUrl: https://opencode.ai/zen/go/v1/usage
    statusUrl: https://opencode.ai/console/api/go/status
    enrich: true
    refreshMs: 60000
    timeoutMs: 15000
    monthlyLimitUsd: 60
    planLabel: Go
    debug: false

Regarding data sources, the percentages and reset times for the three windows come from GET https://opencode.ai/zen/go/v1/usage; the plan name, billing cycle, exact dollar amount, and used amount come from GET https://opencode.ai/console/api/go/status (using the same Key). The latter is an internal Console interface. On failure, it automatically falls back to estimation based on the official Go usage guide: 5-hour window = 20% of monthly quota, weekly = 50%, monthly = 100%. The monthly limit defaults to $60.

Status Semantics & Validation¶

API read results map to fixed states, and the interface behaves accordingly: null indicates a successful read and displays the three windows; no-key jumps to the settings page; unauthorized, no-subscription, network, bad-shape, bad-json, http-*, etc., correspond to red error prompts or retaining the last snapshot.

The README records the test results on DSH 0.2.1-rc.3 (Windows, Web GUI): On the Host side, GET /opencode-go-usage/api/state returns 200, keySource: "credentials", and ?refresh=1 actually triggers a re-fetch; POST /api/key with invalid parameters returns 400, and CORS returns 403. On the Client side, the conversation.composer.dock slot is valid. The pill has a logical size of approximately 151×18, the popup’s left edge aligns with the pill’s left edge, and the details card is 334×169.

Applicable Scenarios & Notes¶

This is suitable for users who want to see the remaining OpenCode GO quota and reset time directly in the DSH interface without opening a web page or writing scripts, and also for scenarios where multiple OpenCode accounts are managed and their usage needs to be distinguished.

Before using, please confirm three things:

1. The plugin runs with the permissions of the current DSH process. The Host side makes requests to opencode.ai with the Key. You should check the source code and the MIT license before installing.

2. The usage API has no public documentation, and the official side may adjust it. The plugin performs defensive parsing. /console/api/go/status is an internal interface, and failure only affects the exact dollar amount and plan information; the percentages display normally.

3. Percentages are account-level data, including usage from other devices/clients of the same account. The same Key in the credential service and auth.json might belong to different accounts.

Closing¶

The value of this plugin is clear: it moves the three-window quota of OpenCode GO from the web page into the area below the DSH input box. It does not have a persistent panel, does not occupy layout, and does not modify model configuration.

Directory page: https://www.skillhub.cn/plugins/zyhnbyyds/dsh-opencode-go-usage
GitHub: https://github.com/zyhnbyyds/dsh-opencode-go-usage