# AGENTS.md ## Project `opencode-greenpt-usage` — an OpenCode **v2** CLI/TUI plugin (Solid + OpenTUI) that shows the remaining GreenPT API credit balance in the sidebar. Distributed by `git clone`; there is no npm publish. The `main` branch targets OpenCode 1.x; this branch targets OpenCode `>= 2.0.0`. ## Commands ```bash npm install # install dev dependencies npm test # unit tests (vitest) npm run typecheck # tsc --noEmit GREENPT_API_KEY=... npm run test:integration # live API test ``` ## Conventions - The plugin has two entries: `src/index.ts` (server side, minimal `Plugin.define`) and `src/tui.tsx` (CLI plugin, exposed as `./tui`). Types come from `@opencode/plugin` and `@opencode/plugin/tui`; the host provides `solid-js`, `@opentui/solid` and the theme at runtime. - The section is appended to the `sidebar.content` slot and is hidden when no GreenPT credential is present (`showWhenUnavailable` opts into a hint). - Commands are registered through `context.keymap.layer` (palette). - Balance probing must stay **free**: `HEAD /v1/chat/completions` returns `400` plus `x-credits-remaining`. Never replace it with a billable call. - Usage accounting lives in `src/usage.ts` (pure) and is consumed by the balance store: real spend = delta of `x-credits-remaining` between probes; per-model detail = reconciliation of local OpenCode assistant messages, idempotent by message id, persisted in the plugin durable storage (`context.storage.store`). - Credential resolution order: `apiKey` option, `GREENPT_API_KEY`, active OpenCode `auth.json` (`greenpt`, `type: "api"`). No profile-switching command may leak into this logic. - No code comments unless functionally required.