# opencode-greenpt-usage An [OpenCode](https://opencode.ai) **OpenCode 2** TUI plugin that shows the remaining **GreenPT API credit balance** and the **consumption** of the API key (real credit spend plus a per-model breakdown) in the sidebar. ``` ▼ GreenPT Balance 5.31 € updated 21:35 Spent today 0.04 € month 0.31 € glm-5.3-flash 12.4k tok ~0.02 € kimi-k2 3.1k tok ~0.01 € ``` ## How it works - The API key is resolved in this order: 1. the plugin `apiKey` option; 2. the `GREENPT_API_KEY` environment variable; 3. the **active** OpenCode auth store (`auth.json`, provider `greenpt`, entry `type: "api"`) — i.e. exactly what a plain `opencode auth login` produces. - The balance is read with a **free** `HEAD /v1/chat/completions` probe: the API answers `400 Bad Request` before any billing, yet the response still carries the `x-credits-remaining` header. No credit is consumed and no generation is triggered. - **Usage tracking** keeps per-day buckets, persisted in the plugin's durable TUI store (90 days by default): - *real credit spend* is observed as the drop of `x-credits-remaining` between two balance probes — this covers **every client** of the API key, not just OpenCode, but has no per-model detail; - *per-model breakdown* (tokens and estimated cost) is reconciled from the GreenPT assistant messages of your local OpenCode sessions — this detail is therefore **local to this machine** and priced with OpenCode's model catalog, which may differ from GreenPT's credit pricing (estimates are marked with `~`). - At startup, the last 10 sessions are reconciled to backfill recent history; counters can be cleared with `greenpt.usage.reset`. - The section is **hidden while no GreenPT key is present**. - Refresh happens on startup, at the end of a session, on server reconnection, on a timer (300 s by default) and on demand through the `greenpt.refresh` command; usage buckets are reconciled on each refresh and at the end of each session. There is no dependency on any local profile or command: the plugin only looks for a key. ## Requirements - OpenCode `>= 2.0.0` (V2 TUI plugin API). - A GreenPT account and API key. ## Installation 1. **Clone this repository** wherever you keep your projects. 2. **Connect GreenPT to OpenCode**: ```bash opencode auth login ``` Pick **GreenPT** from the list, then paste the API key. (Alternative: export `GREENPT_API_KEY` in your environment.) 3. **Register the plugin** in `~/.config/opencode/cli.json`, pointing at the **repository directory** (the package's `./tui` export): ```jsonc { "$schema": "https://opencode.ai/v2/cli.json", "plugins": [ { "package": "file:///ABSOLUTE/PATH/TO/opencode-greenpt-usage", "options": { "refreshInterval": 60 } } ] } ``` > V2 loads a package directory, not a source file. Do not point at > `src/index.tsx`: a configured file is skipped. OpenCode compiles the TSX > entrypoint itself. 4. **Reload OpenCode**. V2 reloads configuration and plugins after a save; if a running session keeps the old module, quit and relaunch it. ## Configuration All options are optional and go in the plugin entry of `cli.json`: | Option | Type | Default | Description | | --------------------- | ------- | --------------------------- | ------------------------------------------------------- | | `apiKey` | string | resolved automatically | Explicit GreenPT key. | | `baseUrl` | string | `https://api.greenpt.ai/v1` | GreenPT API base URL. | | `refreshInterval` | number | `300` | Refresh interval in seconds (`0` disables the timer). | | `order` | number | ignored | Accepted for V1 compatibility; V2 orders slots by plugin load order. | | `showWhenUnavailable` | boolean | `false` | Show a hint when no GreenPT key exists. | | `unit` | string | `€` | Unit appended after the amount. | | `trackUsage` | boolean | `true` | Track credit spend and per-model usage. | | `usageWindowDays` | number | `90` | Retention window for per-day usage buckets. | | `usageBackfill` | number | `10` | Recent sessions reconciled at startup (`0` disables). | ## Troubleshooting - **The section does not appear**: make sure `opencode auth login` stored a `greenpt` key (or that `GREENPT_API_KEY` is set), and that the `file://` entry in `cli.json` points at the **repository directory**, not at `src/index.tsx`. Check that `opencode plugin list` lists your repository directory. - **"invalid GreenPT key"**: the API key was rejected (HTTP 401). - **"balance unavailable"**: GreenPT did not return the balance header; try again later. ## Development ```bash npm install npm test # unit tests npm run typecheck # type check GREENPT_API_KEY=... npm run test:integration # test against the live API ``` ## License AGPL-3.0-or-later. See [LICENSE](LICENSE).