gentle-opencode-go
OpenCode Go subscription usage in Gentle Shell's status bar and /gentle:usage panel
Package details
Install gentle-opencode-go from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:gentle-opencode-go- Package
gentle-opencode-go- Version
0.1.2- Published
- Nov 7, 2026
- Downloads
- 826/mo · 48/wk
- Author
- jesdev
- License
- MIT
- Types
- extension
- Size
- 143.2 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"./src/extension.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
OpenCode Go subscription usage in Gentle Shell — the status bar segment and the /gentle:usage panel behind alt+u.
Gentle Shell ships built-in usage readers for Codex, Claude and NaN Cloud. OpenCode Go subscriptions have none, so alt+u never moves while you use an opencode-go model. This package registers OpenCode Go as a usage source, and Gentle Shell treats it exactly like a built-in one.
main ±3 │ SUPER-YOLO deepseek-v4.1-flash · high │ ctx ▰▰▰▰▱▱▱▱ 8% │ $0.390 │ usage 5h ▰▰▱ 0% · week ▰▰▰▰▱ 44% · 30d ▰▰▰▰▰ 55% · alt+u
Requirements
- Gentle Shell with a
usage-sourcecapable version (the event contractgentle-pi:usage-source/v1, documented indocs/gentle-shell.md) - Pi
>= 0.85, Node>= 22.19 - An
opencode-goprovider configured in Pi, with its API key stored as usual (auth.jsonorOPENCODE_API_KEY)
Install
Gentle Shell has its own package command, and it matters which one you use. The standalone gentle-shell runs in its own home (~/.gentle-shell/agent), while a plain pi install writes to ~/.pi/agent — the home you only see if you launch pi yourself.
# Standalone Gentle Shell (the usual case)
gentle-shell install npm:gentle-opencode-go
# Gentle Shell linked to an existing pi home (--link)
gentle-shell --link install npm:gentle-opencode-go
# Plain Pi
pi install npm:gentle-opencode-go
Or from a checkout, for development:
gentle-shell install ./gentle-opencode-go
Then reload (/reload) or restart, send one message with an opencode-go/* model, and open alt+u. Use r in the panel to fetch immediately.
Plain Pi has no listener for this event, so the extension is a no-op there. Its only effect is inside Gentle Shell.
What it looks like
In the status bar, after the session cost:
deepseek-v4.1-flash · high │ ctx ▰▰▱▱▱▱▱▱ 20% │ $0.661 │ usage 5h ▰▱ 4% · week ▰▰▰▰▱ 46% · 30d ▰▰▰▰▰ 56% · alt+u
alt+u opens the panel, one row per window:
✿ Subscriptions
opencode-go · OpenCode Go · updated just now
OpenCode Go 5h ▰▱▱▱▱▱▱▱ 4% · resets in 3h 16m
OpenCode Go week ▰▰▰▰▱▱▱▱ 46% · resets in 1d 7h
OpenCode Go 30d ▰▰▰▰▰▱▱▱ 56% · resets in 17d 5h
The percentages are what the endpoint answered at the last refresh, never an average or an estimate.
How it works
One authenticated, read-only GET to a fixed route:
https://opencode.ai/zen/go/v1/usage
That is the same route the OpenCode console uses for the workspace dashboard. It answers with three windows, each a used percentage and a reset time:
{ "usage": {
"rolling": { "status": "ok", "percent": 0, "resetsAt": "2026-11-07T19:45:51.000Z" },
"weekly": { "status": "ok", "percent": 44, "resetsAt": "2026-11-09T00:00:00.000Z" },
"monthly": { "status": "ok", "percent": 55, "resetsAt": "2026-11-24T21:47:15.000Z" }
} }
The API key is the one Pi already holds for the provider. It is passed in by Gentle Shell at fetch time, used only in the Authorization header, and never stored, logged or returned.
Security
This package handles a credential, so its behaviour is deliberately narrow and auditable:
- One destination, hardcoded. The only URL literal in the source is
https://opencode.ai/zen/go/v1/usage. There is no configuration, argument or environment variable that can point the bearer anywhere else. - No redirects. The request uses
redirect: "error", so a3xxcannot replay the token to another origin. - Read-only. Only
GET. No writes to disk, no changes tosettings.json,auth.jsonor any other file, no shell, noeval. - No logging, no telemetry. The source contains no
console.*, no stream writes and no analytics. Failures resolve toundefinedand are reported to you only as Gentle Shell's generic, non-secret "fetch failed" note. - The key never leaves the header. It is not part of the returned snapshot, so it cannot reach the panel, the sidebar or a session file.
- No runtime dependencies and no install scripts. There is no
dependenciesblock and nopreinstall/postinstall, so installing the package executes nothing. - Defensive parsing. The payload is foreign JSON: every field is checked and rebuilt, never merged into an existing object, so a hostile payload cannot pollute a prototype or crash the shell.
Review the source before installing any third-party package: it is two files under src/.
Known limits
- Window lengths are not published by the endpoint. The labels
5h,weekand30dare fixed in the source. The month is approximated at 30 days. These only drive the label, the meter width and the ordering; the percentage and the reset time always come from the server. statushas no published meaning beyond the"ok"value the endpoint returns today. It is never interpreted: the percentage is always shown as reported, and any other status only raises the limit flag.- The endpoint can trail the OpenCode console by a point. While usage is advancing,
GET /zen/go/v1/usagehas been observed reporting one point less than the workspace dashboard on all three windows at once (dashboard 2/46/56 against endpoint 1/45/55). The gap is on OpenCode's side: this package reports exactly what the endpoint answers, never a smoothed or adjusted value. The two surfaces are usually identical, so treat the dashboard as the leading indicator while a window is moving. - The endpoint is outside OpenCode's published OpenAPI, so its shape may change. A malformed or empty payload is dropped rather than guessed, which means the segment can disappear instead of showing wrong numbers.
- It reflects the subscription, not this session. Usage you spend in the OpenCode CLI counts too.
Development
npm install
npm run verify # tsc --noEmit, then node --test
License
MIT — see LICENSE.
The Gentle-AI rose is the mark of Gentleman Programming, used here only to say what this package targets. This is a community package: it is not an official Gentleman Programming release.