go-pane

[!NOTE] This project is primarily for personal use, hence the specific target environment. However, codebase quality is also a main goal and it should work in any compatible environment (Plasma 6 KDE) and contributions of any kind (issues, feature requests, etc) are very much welcome.

A native KDE Plasma 6 widget that shows live OpenCode Go subscription usage (rolling / weekly / monthly) with reset countdowns and derived pacing metrics.

As of v0.2.0 the whole thing is a single, self-contained QML plasmoid. There is no daemon and no Go toolchain: the applet calls the OpenCode Go usage API directly, derives every metric in JavaScript, and discovers the API key from the same places the old daemon used (plus a manual override). Key discovery was restored in v0.2.1.

1OpenCode Go API ──> Plasma applet (single main.qml + KConfig)

Features

• Rolling, weekly and monthly usage, matching the OpenCode dashboard.
• Available % left and reset countdown (19d 5h, 4h 59m, …).
• Derived metrics: pace ratio, projected usage at reset, exhaustion ETA and a safe %/h budget.
• Compact panel representation (three bars + most-constrained headline) and a detailed popup.
• Configurable API key, base URL, refresh interval, warning/critical thresholds, visible windows and panel headline, all from the widget's popup.
• Automatic API key discovery (env vars, ~/.config/go-pane/…, ~/.pi/agent/auth.json) with a manual override.
• Stale/error states and a one-click refresh.

Requirements

• KDE Plasma 6 (kpackagetool6 and plasma5support)
• An OpenCode API key (oc_sk_…). The OAuth token used by the opencode CLI is not accepted by the usage endpoint.

Go is not required anymore. plasma5support is used only to run the key discovery command once at startup.

Install

Download go-pane-0.2.1.plasmoid from the latest release and install it:

1kpackagetool6 -t Plasma/Applet -i go-pane-0.2.1.plasmoid

Or build it from a git clone:

1git clone https://github.com/4ster-light/go-pane.git2cd go-pane3make install

make package builds the .plasmoid archive from the sources if you prefer to install that way.

Then right-click the panel, choose Add Widgets…, and add OpenCode Go Usage. The widget discovers an existing API key automatically; if it cannot find one it opens its settings so you can paste it.

To upgrade an existing install:

1make plasmoid-upgrade

Configuration

Open the widget's popup and click the gear (⚙). Settings are saved in the widget's Plasma configuration (a 0600 file):

API key discovery

If the widget's API key field is empty it discovers the key automatically, first match wins:

1. OPENCODE_API_KEY
2. OPENCODE_GO_API_KEY
3. ~/.config/go-pane/api_key (plain text)
4. ~/.config/go-pane/config.json → apiKey
5. ~/.pi/agent/auth.json → opencode-go.key

Anything you type into the API key field takes precedence and is stored in the widget's Plasma configuration. The 🔍 button next to the field re-runs discovery, and the popup shows which source is currently in use.

Notes

• The usage endpoint (GET /zen/go/v1/usage) is undocumented and may change; the base URL is configurable.
• Window lengths are inferred and fixed: rolling ≈ 5h, weekly 7d (Monday 00:00 UTC) and monthly 30d (a signup anniversary). Pacing for the monthly window is therefore an estimate. The old daemon learned exact lengths from history.
• The API sends access-control-allow-origin: *, which is what allows the QML XMLHttpRequest to call it directly.

Security

The API key is a bearer credential. When auto-discovered it is only read into memory and never copied to KConfig; if you enter it manually it is written to the widget's Plasma configuration (a 0600 file, not encrypted). Rotate the key in the OpenCode console if it leaks.

Development

1make dev        # upgrade the applet and open it with plasmawindowed2make check      # static package validation (metadata, KConfigXT, QML refs)3make package    # build dist/go-pane-<version>.plasmoid

There is no prebuilt binary or test suite: the widget is the single contents/ui/main.qml. Optional dev packages for validation: qmllint (from qt6-qtdeclarative-devel on Fedora).

CI runs scripts/validate_package.py, which checks the package layout, the metadata.json, the KConfigXT schema and that every configuration key used in the QML is declared.

License

MIT