# AGENTS.md ## Project `opencode-greenpt-usage` — an OpenCode **2** TUI plugin (Solid + OpenTUI) that shows the remaining GreenPT API credit balance in the sidebar. Distributed by `git clone`; there is no npm publish. ## 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 entry is `Plugin.define({ id: "greenpt.usage", setup })` in `src/index.tsx` (default export). Types come from `@opencode/plugin/tui` and `@opencode/plugin/tui/context` as **type-only** imports; the host provides `solid-js` and `@opentui/*` at runtime. - The section is registered on the `sidebar.content` slot via `context.ui.slot({ append: ..., render })`, hidden when no GreenPT credential is present (`showWhenUnavailable` opts into a hint). Commands use `context.keymap.layer`; `setup` returns a cleanup that unregisters the slot and disposes the store. - 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 (V2 `type: "assistant"`, `model.providerID`/`model.id`), idempotent by message id, persisted with `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 explanatory inline comments; function contract blocks are required.