opencode-go-usage

Monitor your OpenCode Go subscription usage directly from TUI, Desktop, and IDE.

Exposes a /gousage custom tool that shows rolling (5h), weekly, and monthly usage percentages with reset timers and ASCII progress bars.

Installation

Via npm

npm install opencode-go-usage
npx playwright install chromium

Then add to your opencode.json:

{
  "plugin": ["opencode-go-usage"]
}

Manual (local plugin)

Clone or copy this repo into .opencode/plugins/opencode-go-usage/ in your project:

git clone <this-repo> .opencode/plugins/opencode-go-usage
cd .opencode/plugins/opencode-go-usage
npm install
npx playwright install chromium

Then reference it in opencode.json:

{
  "plugin": ["./.opencode/plugins/opencode-go-usage"]
}

Usage

As a custom tool

Invoke /gousage in any OpenCode client (TUI, Desktop App, or IDE extension):

/gousage

Or ask the LLM naturally:

Check my Go usage

Example output

OpenCode Go Usage
─────────────────────────────────────────────
 Rolling (5h)   ████████░░░░░░░░░░░░  26%
                Resets in 4h 49m

 Weekly         ██████████████░░░░░░  68%
                Resets in 8h 34m

 Monthly        █░░░░░░░░░░░░░░░░░░░   5%
                Resets in 29d 20h
─────────────────────────────────────────────
 Use balance:   No

Force refresh

Bypass the 1-minute response cache:

/gousage refresh=true

First-time setup

1. Invoke /gousage
2. A browser window opens to the OpenCode OAuth page
3. Sign in with GitHub or Google
4. The auth cookie is saved automatically to ~/.config/opencode/plugins/opencode-go-usage/
5. Your workspace ID is auto-detected from the post-login redirect

Subsequent invocations use the saved cookie — no login required. The cookie lasts 1 year.

Configuration

Environment variables

| Variable | Description | |---|---| | OPENCODE_GO_WORKSPACE_ID | Override workspace ID (e.g. wrk_01KQQB5Z8AQ0K0K297VZJBQ3FQ) |

Config file

~/.config/opencode/plugins/opencode-go-usage/config.json:

{
  "workspaceId": "wrk_...",
  "cacheTtlMs": 60000,
  "serverFnIdCacheTtlMs": 86400000
}

How it works

1. OAuth login: Uses Playwright to open the OpenCode auth page, captures the auth cookie from the browser context after OAuth completes.
2. Server function ID: Scrapes the workspace /go page to find the current SolidStart server function hash (changes on each deploy). Cached for 24h.
3. Usage endpoint: Calls https://opencode.ai/_server?id=<hash>&args=<seroval> with the auth cookie.
4. Response parsing: Extracts usage data from the Seroval streaming format via regex.
5. Caching: Responses are cached for 60 seconds to avoid rate limiting.

Troubleshooting

| Issue | Fix | |---|---| | "Playwright is not installed" | Run npx playwright install chromium | | "AUTH_EXPIRED" | Cookie expired — invoke /gousage again to re-login | | "SERVER_FN_NOT_FOUND" | Server function ID changed — invoke /gousage again to re-scrape | | "No workspace ID configured" | Set OPENCODE_GO_WORKSPACE_ID or re-login to auto-detect | | "Failed to parse usage response" | OpenCode may have changed their response format — open an issue |

Architecture

src/
├── index.ts          Plugin entry point
├── auth/
│   ├── oauth.ts      Playwright OAuth flow
│   ├── cookie-store  Cookie persistence (chmod 600)
│   └── validator.ts  Cookie validation
├── api/
│   ├── client.ts     HTTP client for usage endpoint
│   ├── parser.ts     Seroval response parser
│   ├── scraper.ts    Server function ID scraper
│   └── types.ts      TypeScript interfaces
├── tools/
│   └── gousage.ts    Custom tool definition
├── utils/
│   ├── format.ts     ASCII bars, duration formatting
│   ├── cache.ts      Generic TTL cache
│   ├── config.ts     Config read/write
│   └── paths.ts      File path resolution
└── constants.ts      URLs, thresholds, defaults

Works identically across all OpenCode clients (TUI, Desktop App, IDE extensions) because the plugin runs server-side and returns plain text.

License

MIT

Disclaimer: This project is not built by the OpenCode team and is not affiliated with them in any way.