# OCG Usage
**DeepSeek balance and OpenCode Go usage (5-hour / weekly / monthly) merged into one floating pill, with a matching settings page**
[](README.md) [](README.en.md)
[](https://github.com/verneuil/dsh-opencode-go-usage/actions/workflows/ci.yml)
[](https://github.com/verneuil/dsh-opencode-go-usage/actions/workflows/codeql.yml)
[](LICENSE)
[](https://github.com/verneuil/dsh-opencode-go-usage/releases/latest)
[](https://www.npmjs.com/package/@verneuil/dsh-opencode-go-usage)
[](https://dsh-plugin.org/plugins/verneuil/dsh-opencode-go-usage)
[](https://www.dsh.so/artifact/dsh-opencode-go-usage-15/)
[](https://awesome-dsh-plugin.com/p/verneuil/dsh-opencode-go-usage)
[Changelog](CHANGELOG.md) · [Feedback](https://github.com/verneuil/dsh-opencode-go-usage/issues)
---
*An unofficial [DeepSeek Harness](https://github.com/deepseek-ai) plugin that shows your DeepSeek balance and OpenCode Go usage (Rolling / weekly / monthly) in one floating pill, with click-to-refresh, border-flash feedback, drag-to-snap and a hover popover, plus a full-page settings view of its own.*
## Contents
- [Features](#features) · [Installation](#installation) · [Usage](#usage) · [Settings page](#settings-page)
- [Screenshots](#screenshots) · [Data sources](#data-sources) · [Anatomy](#anatomy)
- [Configuration](#configuration) · [Robustness](#robustness) · [Known limitations & disclaimer](#known-limitations--disclaimer) · [License](#license)
## Features
**The pill and the hover popover**
- **OpenCode Go quota amounts + DeepSeek balance display**:
- The balance area on the pill's left can show either the **DeepSeek balance** or the **OCG quota remaining worked out from a reference model**;
- the OCG model list and quota are fetched automatically, falling back to the bundled model table and quota data when the fetch fails.
- **Three rings show each window's usage**:
- OpenCode Go's three windows are drawn as ring progress indicators, and **clicking the pill refreshes them**;
- the number in each ring's centre is a percentage (**Used** by default, switchable to **Left** in settings): > 20% left green / ≤ 20% amber / ≤ 5% red.
- **Hover popover**:
- hovering the pill opens a panel with three separate usage bars showing the percentage and the reset time;
- it can also show both balances at once (**DeepSeek account balance** and **OpenCode Go quota left** — either can be switched off on the “Floating pill” tab).
- **OCG quota conversion**:
- pick a **reference model** on the settings page (DeepSeek V4.1 Flash by default; any official OpenCode Go model is available) and the plugin works out the **used / remaining amount** from “that model's **Go-tier** monthly quota × this month's used percentage”, shown both in settings and in the hover popover;
- free models read “Free”, unlimited ones “Unlimited”, and the remaining quota and similar figures all show `--` .
- **Amount currency**:
- every amount (the DS balance and the OCG quota) can be priced in **¥ CNY / ＄ USD / auto** (¥ in the Chinese UI, ＄ in the English UI);
- the rate is fetched automatically, falls back to a bundled rate, and conversion only affects the display.
- **Minimal mode**:
- **Ring data mapping**: each of the outer / middle / inner rings can show "5 hours / Weekly / Monthly", with a live preview on the right (minimal mode only);
- three **nested** rings (R inner / W middle / M outer) with the balance **rounded to whole units** shown beside them — a more compact pill (the normal mode is “balance + three separate rings”);
- turning “show a balance on the pill's left” off as well gives the **most compact form**: nested rings only, taking up the least space.
- **Other details**:
**The popover is interactive**: moving the pointer from the pill onto the popover keeps it open (a 220 ms grace period covers the gap between the two), clicking the popover behaves exactly like clicking the pill (a manual refresh), and its border flashes in sync with the pill;
**The popover picks its direction**: it opens upwards near the bottom of the window and inwards near the left/right edges, so it is never clipped;
**Drag to snap**: on release the position is recorded against the **window edges only** (so it no longer drifts when the composer card changes size), with 0.1px precision, and the pill keeps its relative position when the window resizes;
- **Fixed size**: the pill never changes size in any state (the feedback layer is an absolutely positioned overlay that does not participate in layout).
**Optional sidebar entry**: a "Sidebar entry" switch in settings (off by default). When enabled the plugin gets a sidebar row that opens its settings page as a full page (the very same UI), with the settings-menu mark as its icon;
**General**
- **Zero dependencies**: plain JavaScript — **no build step, no third-party runtime dependencies** (only `require('react')`, provided by the host).
- **Bilingual UI**: every interface string goes through the client locale dictionaries and follows the DSH language setting instantly (pill, settings page, menu label and all action messages).
## Installation
**Requirements**: DeepSeek Harness desktop (the app bundles node / pnpm — nothing else to install). This plugin follows the official DSH plugin conventions: you do **not** hand-edit the profile's `package.json` / `cordis.patch.yml`, and you should not run pnpm inside the profile directory.
In DSH, open the **plugin manager → “Install plugin” dialog → paste one of the specs below → install** (the dialog drives pnpm and installs one spec at a time):
| Method | Spec to paste |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Straight from GitHub** (recommended) | `github:verneuil/dsh-opencode-go-usage` |
| **From npm** | `dsh plugin --profile web add @verneuil/dsh-opencode-go-usage` |
| **Pin a version** | `github:verneuil/dsh-opencode-go-usage#v3.4.1` (replace with any published tag) |
| **Release tarball** | `https://github.com/verneuil/dsh-opencode-go-usage/releases/download/v3.4.1/dsh-opencode-go-usage-3.4.1.tgz` |
| **Release URL (always latest)** | `https://github.com/verneuil/dsh-opencode-go-usage/releases/latest/download/dsh-opencode-go-usage.tgz` |
| **Offline tgz** | `file:D:/your/path/dsh-opencode-go-usage-3.4.1.tgz` |
The equivalent command line (`dsh plugin` automatically adds dependencies that declare `dsh.bundle` to the profile's bundles — no hand-written patch needed):
```sh
dsh plugin --profile web add github:verneuil/dsh-opencode-go-usage
```
Follow the on-screen prompt to reload afterwards (replacing an installed JavaScript module generation requires restarting DSH).
- **Bundle-only installs**: the plugin manager rejects dependencies without a bundle patch; this package ships its own `cordis.patch.yml`, so it qualifies.
- **Upgrading = uninstall then reinstall**: the plugin manager offers no version picker and no upgrade button. Uninstalling removes the dependency record and reinstalling resolves it afresh, so **that is how you get a new version**; installing the same spec over the top will not pick up a new commit.
- Every version's changes are listed in [CHANGELOG.md](CHANGELOG.md) (Chinese and English).
## Usage
- **Click the pill** = refresh the balance, the usage, the model list and the exchange rate immediately (or just wait for the automatic refresh).
- **Drag the pill** = move it; it snaps on release. The “Reset position” button restores the default position (top-left of the window).
- **The balance line on the pill's left** = pick one in settings: **DS balance** / **OCG quota left** (see [Settings page](#settings-page)).
- **Settings page** = `Settings → Plugins → OCG Usage`.
## Settings page
The settings page has three tabs: **Usage data** (default) / **Floating pill** / **General settings**.
Next to the page title sit the **GitHub icon and the current version** (e.g. `v3.4.1`); clicking the icon opens this repository.
**Usage data**
- **Quota reference model**: a dropdown listing every official OpenCode Go model (default **DeepSeek V4.1 Flash**); the note beneath shows the **model-table update time** and the result of this refresh.
- **Amount display currency**: a three-way choice — `Auto` / `¥ CNY` / `＄ USD`; the note beneath shows the **current rate, when it was fetched** and the refresh result.
- **Plan quota**: `Model: X (total: Z, used: Y, left: W)`; the amounts come from the **reference model's Go-tier monthly quota × this month's used percentage**.
- **Usage details**: a progress bar, the percentage (basis is selectable), reset countdown and API status for each of the three windows.
- **Progress basis** (top-right of the usage card): **Used** / **Left** — right next to it sits the **OpenCode icon**, which opens the [OpenCode account page](https://opencode.ai/console). The pill and the settings rows follow the same basis; defaults to **Used**.
- Two rows below the card:
- **manual refresh + last-updated time** (after a successful refresh it shows “Updated (time)” and **falls back to “Last updated: …” after 3 seconds**);
- the **auto-refresh interval** (set a number of minutes and save; range 0.5 – 1440).
- **Failures name the source**: whenever a fetch fails, the error line appears **left of the manual refresh button** (and at the very bottom of the hover popover), stating whether **OCG usage / DeepSeek balance / the rate / the model table and quota** failed.
**Floating pill**
- **Pill master switch**: turning it off greys out the rows below and makes them non-interactive.
- **Pill size**: a slider with eight stops where only the “Default 100%” stop carries a label — two stops to the left (−10%, −20%) and five to the right (+15%, +30%, +50%, +75%, +100%), i.e. 80% – 200%; the balance, the rings and the hover popover scale together and anchor-based positioning keeps working.
- **Show a balance on the pill's left** (switch): shows one balance line on the pill's left; turning it off also collapses the row below.
- **Pill left-side balance data** (two-way): `DS balance` / `OCG quota left` — which data that left line uses.
- **Hover popover balance data** (checkbox dropdown): `DS balance` / `OCG quota left` — show one, both, or **neither** (the popover then keeps only the three progress bars); **clicking outside the dropdown closes it**.
- **Minimal mode** (switch): nested rings (outer / middle / inner) with the rounded balance shown beside them.
- **Ring data mapping** (only available in minimal mode): choose which of “5 hours / Weekly / Monthly” each of the outer / middle / inner rings shows, with a live preview on the right (the three segmented controls are labelled Outer / Middle / Inner).
- **Reset the pill position**: back to the default position (top-left of the window).
**General settings**
- **API Key** section: **overrides for both keys** (leave empty to use the DSH credential store; clear them at any time to go back to automatic).
- **Settings** section:
- **Sidebar entry** (switch): when enabled the DSH sidebar shows a row for this plugin that opens its full settings page; off by default and it never affects the settings page itself;
- **Restore defaults**: one click writes back “Used basis / 5-minute auto-refresh / Minimal on / no balance on the pill / reference model DeepSeek V4.1 Flash / currency auto / left source DS balance / both popover balances shown / default top-left position”.
**Shared behaviour**
- **Per-row feedback**: each action's message appears in the row it belongs to — red on failure, green on success. Messages live in a slot on the title row, so **showing and hiding them does not shift the layout**, and they disappear after 3 seconds.
- **Hints wrap first**: when a title or hint competes with the control on the right, the hint wraps onto more lines while the control stays on the same row, right-aligned; long titles wrap too instead of being truncated;
- **Animated segmented controls**: every two/multi-choice control (the three settings tabs, progress mode, amount currency, pill-balance source and the ring mapping) slides its selected pill to the target position (240 ms); switching settings tabs also fades the panel in with a slight rise (220 ms). All of it is disabled automatically when the system asks for reduced motion.
Because the plugin ships its own settings page, the host side calls the official `settings.configure({ auto: false })` to switch off the auto-generated form, avoiding two duplicate configuration UIs.
## Screenshots
> All ten are **rendered illustrations** built from the plugin's real stylesheet and the host theme tokens (not machine screenshots). The three settings groups cover every tab: **Usage data** (quota reference model, amount currency, plan quota and the usage card), **Floating pill** (master switch, size slider, balance and popover data, minimal mode, ring data mapping with its live preview, position reset) and **General settings** (both keys, sidebar entry, restore defaults, export / import configuration). The states image includes the latest hover popover, and the last one shows the full settings page opened from the sidebar entry.
| Pill · light | Pill · dark |
| --- | --- |
|  |  |
| **Settings · Usage data (light)** | **Settings · Usage data (dark)** |
|  |  |
| **Settings · Floating pill (light)** | **Settings · Floating pill (dark)** |
|  |  |
| **Settings · General settings (light)** | **Settings · General settings (dark)** |
|  |  |
| **Sidebar entry · full settings page** (what the sidebar row opens when the entry is enabled) | |
|  | |
**States and colour grades** (refreshing / success / failure / three grade colours / minimal mode / most compact form / narrowed after hiding the balance)
## Design goal: minimal
- Blend into the existing DeepSeek Harness UI as much as possible: unobtrusive, never shouting, yet still letting you read your usage at a glance — evolved from a long progress bar into the three rings you see today.
- Only OpenCode Go is supported for now; other coding plans have not been tackled yet.
## Data sources
```
GET https://opencode.ai/zen/go/v1/usage # OpenCode Go usage
Authorization: Bearer