Preface¶

The philosophy of DSH is “everything is a plugin.” Even trivial tasks like querying usage should be handled by a plugin rather than manually opening a webpage and switching back. People using OpenCode Go have a recurring action: while writing code, they want to know how much of the 5-hour quota remains, so they switch to the Console, note down the number, and switch back. The positioning of this plugin is to bring this action back into the Harness interface—placing a badge at the bottom of the input bar and a section in the Settings page, with nothing else added.

The plugin introduced below is maintained by Jfreey, categorized as “Client” in the community directory SkillHub, and is currently installed by pointing the plugin manager to the repository. It does one thing: display OpenCode Go usage. No extra interfaces, no extra dependencies, no build steps required.

What is this¶

One-sentence positioning: A lightweight DSH client plugin that displays OpenCode Go’s three types of quotas (5-hour rolling, weekly, monthly) in the composer dock’s badge and the Settings page.

It solves the problem of “usage visibility.” The plugin reads the three tiers of quotas from https://opencode.ai/zen/go/v1/usage, authenticates using the key you have saved, and renders the percentage and reset time into a progress bar. The key does not enter the browser; the page only receives the percentage and reset time.

Maintainer: Jfreey. License: MIT, LICENSE file included in the repository.

Core Features¶

Input Bar Bottom Badge. Displays a compact Go [progress bar] 5h 13% badge in the composer dock, positioned to the left of the Turn-count badge. The progress bar can be toggled off, the tracking level (5h / week / month) is configurable, and it can also rotate automatically at a set time.

Expanded Panel. Hovering, clicking, or focusing on the badge opens a panel containing one progress bar for each of the three quotas, along with the used percentage, reset countdown, manual refresh button, and toggles for the progress bar, level, and rotation. Changes here are saved locally in the browser.

Settings Page. The Settings → OpenCode Go section contains three cards. When opened, it reads the cache first without querying the upstream again; after that, it auto-refreshes every 60 seconds, and the button is used to fetch immediately.

Bilingual (Chinese and English). The UI follows the Harness application language, and the plugin registers two sets of entries for Chinese and English. Reading data goes through the host’s read-only route, and the panel indicates that the reading may differ from Console by at most 1 percentage point.

Installation and Enablement¶

The repository itself is an installable bundle (declared as dsh.bundle in package.json). You just need to point the plugin manager in Harness to that directory or the GitHub repository; there is no installation command to type manually. After installation, refresh the page: the Go badge appears at the bottom bar, and the “OpenCode Go” section appears in Settings.

It depends on DeepSeek Harness 0.2.x, specifically using the three contracts dsh.client, ctx.slots, and ctx.locale. If the version is insufficient, upgrade Harness first.

Before installation, it is recommended to read a few files in the repository, especially index.js, client.js, and cordis.patch.yml—the patch file modifies host code, so it is worth confirming the scope of changes before enabling. The license is MIT, allowing commercial use and redistribution.

Configuration¶

The plugin configuration is written in the form of a plugin line:

- id: opencode-go-usage
  name: 'dsh-opencode-go-usage'
  config:
    apiKeyEnv: OPENCODE_GO_API_KEY   # Credential reference name
    # apiKey: oc_sk_...              # Can also write directly, not recommended
    path: /dsh-opencode-go/usage     # Host read-only route
    cacheSeconds: 60                 # Host cache seconds, also bottom bar refresh cycle

    dock: true          # Bottom bar badge master switch
    bar: true           # Progress bar inside badge
    level: rolling      # Tracking level: rolling (5h) | weekly | monthly
    rotate: false       # Level rotation display
    rotateSeconds: 5    # Rotation interval (min 2 seconds), only effective when rotate: true

level also accepts week/w/周 and month/m/月; it falls back to rolling if unrecognizable. Any configuration changes take effect only after reloading Harness (restarting the application or re-enabling the bundle).

Where do keys come from¶

The plugin does not require you to manually write the key; it parses it in the following order:

1. config.apiKey in the plugin line (priority when explicitly filled).
2. The config.apiKeyEnv reference in the credentials service, with the default name OPENCODE_GO_API_KEY—that is the key saved for opencode-go in “Settings → Models”.
3. The process environment variable with the same name.

So as long as opencode-go credentials already exist in the Models page, the plugin can read data directly after installation.

Refresh and Cache¶

Different interfaces behave differently for the same route:

Credential changes (credentials/reference-updated event) clear the cache; the next request after changing the key uses the new credentials and will not continue to display the numbers from the previous account.

HTTP Routes¶

The Host provides a read-only route GET /dsh-opencode-go/usage, with ?refresh=1 forcing a refresh and ?cache=1 reading only the cache. Example of the response body:

{
  "ok": true,
  "fetchedAt": "2026-11-04T12:40:00.000Z",
  "credentialSource": "stored",
  "dock": true,
  "display": { "bar": true, "level": "rolling", "rotate": false, "rotateSeconds": 5 },
  "servedFromCache": true,
  "stale": false,
  "usage": {
    "rolling": { "status": "ok", "percent": 12.5, "resetsAt": "2026-11-04T17:33:21.000Z" },
    "weekly":  { "status": "ok", "percent": 4.1,  "resetsAt": "2026-11-09T00:00:00.000Z" },
    "monthly": { "status": "ok", "percent": 1.2,  "resetsAt": "2026-12-04T12:23:50.000Z" }
  }
}

On failure, it returns { "ok": false, "error": { "code": "NO_KEY|UNAUTHORIZED|FORBIDDEN|TIMEOUT|NETWORK|UPSTREAM|SHAPE", "message": "…" } }, allowing you to distinguish between no key configured, authentication failure, or an upstream exception.

Applicable Scenarios and Notes¶

Suitable for two types of people: those who don’t want to switch windows to check quotas and want usage to always be visible; and those who want to make a similar usage plugin for other providers and need a reference implementation—this plugin has a very small surface, with only two entry points (dock and Settings), and is also small in code volume.

Points to note:

• The plugin runs with the permissions of the current dsh process and can read process environment variables and references in the credentials database. Before installation, check the source code and license to confirm you are willing to let the plugin have these permissions.
• The route is a read-only, same-origin GET that does not go through Harness’s browser login gate. Harness listens only on the loopback address by default; once you expose it to a local network or tunnel, this route will also become accessible.
• The progress bar color uses theme tokens (--dsw-alias-*), applicable to both light and dark themes, requiring no additional adaptation.
• The reading is the integer percentage returned by the interface, differing from Console by at most 1 percentage point, as noted on the plugin panel.

Directory Page: https://www.skillhub.cn/plugins/Jfreey/dsh-opencode-go-usage

GitHub: https://github.com/Jfreey/dsh-opencode-go-usage