Stéphan Sainléger d123b9b3be chg: [opencode-greenpt-usage] tighten the sidebar balance layout
Put the balance on the section header line and keep the folded header to
one row with today's spend. Remove the gap between the title and the
metrics line, then indent model tokens below the full model name so they
read as subordinate detail instead of wrapping mid-name.

The stacked model rows avoid the narrow sidebar splitting a model id;
costs stay right-aligned. Typecheck and the 49 unit tests pass.
2026-11-18 23:13:52 +01:00

opencode-greenpt-usage

An OpenCode 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:

    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):

    {
      "$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

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.

Description
No description provided
Readme AGPL-3.0 274 KiB
Languages
TypeScript 100%