Files
opencode-greenpt-usage/README.md
Stéphan Sainléger 5129f295da new: [opencode-greenpt-usage] port plugin to OpenCode v2
Rewrite the TUI plugin against the OpenCode v2 plugin API
(``@opencode/plugin`` + ``@opencode/plugin/tui``):

- ``src/index.ts``: minimal server-side ``Plugin.define`` entry.
- ``src/tui.tsx``: CLI plugin registered as ``./tui``, appending the
  widget to the ``sidebar.content`` slot through ``context.ui.slot``
  and exposing the refresh/reset commands via ``context.keymap.layer``.
- ``src/store.ts``: durable plugin storage (``context.storage.store``)
  replaces the KV store; ``session.idle``/``session.status`` events and
  the ``client.session`` API drive reconciliation and backfill.
- ``src/widget.tsx``: v2 semantic theme tokens
  (``theme.text.base``/``text.muted``/``text.feedback``).
- Tests updated to a structural fake of the v2 context.

The free ``HEAD /v1/chat/completions`` balance probe and the credential
resolution order are unchanged. The ``order`` option is gone: v2 slot
placement is additive.
2026-10-19 17:00:48 +02:00

126 lines
5.1 KiB
Markdown

# opencode-greenpt-usage
An [OpenCode](https://opencode.ai) 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 durable
storage (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 CLI/TUI plugin system; for OpenCode 1.x use the
`main` branch).
- 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`, setting the
**absolute path to your clone**:
```jsonc
{
"$schema": "https://opencode.ai/v2/cli.json",
"plugins": [
{
"package": "file:///ABSOLUTE/PATH/TO/opencode-greenpt-usage",
"options": { "showWhenUnavailable": false }
}
]
}
```
> Point at the repository root, not at a source file: OpenCode v2 loads
> the `./tui` entry (`src/tui.tsx`) from the package `exports` and
> resolves `@opencode/plugin` at runtime.
4. **Fully quit OpenCode and relaunch it** (plugins are not hot-reloaded).
## Configuration
All options are optional and go in the `options` object of the plugin entry
in `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). |
| `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://`
path in `cli.json` points at the repository root.
- **"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).