V1 TUI modules no longer load: replace ``{ id, tui }`` with
``Plugin.define({ id, setup })``, register the section on
``sidebar.content``, and expose commands through ``context.keymap.layer``.
Move balance, clock and usage state onto ``context.storage.store/memory``
so host subscribers rerender; plugin-created signals stayed stale in the
V2 renderer. Read V2 assistant messages (``type``,
``model.providerID``/``model.id``) and subscribe through ``context.data``.
Configure the package directory in ``cli.json`` instead of the source
file; document the V2 install. Typecheck, 49 unit tests and the live
GreenPT integration test pass, and the sidebar renders the balance.
128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
# 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).
|