opencode-usage

An OpenCode V2 plugin that shows account usage limits in a /usage dialog. It supports OpenAI ChatGPT OAuth accounts; API keys and other providers do not expose usage through this adapter. There is no model-callable usage tool.

Version 0.3.0 requires OpenCode >=2.0.25 <3. For OpenCode V1, keep version 0.2.0.

Install from npm

Add the package to the plural plugins array in your OpenCode server configuration (~/.config/opencode/opencode.jsonc, or a project opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["[email protected]"]
}

OpenCode installs the package and automatically loads its ./tui export in the CLI. Connect OpenAI with /connect, restart OpenCode, then run /usage. Replace any old local/npm entry instead of loading both copies.

Both entrypoints are needed. The server resolves the active OAuth connection and exposes a usage-data RPC; the CLI renders the dialog. Loading this package only in cli.json is not enough. Remove old tui.json/CLI-only entries when switching to server configuration. Against a remote server, install/configure the plugin on that server; credentials and provider requests remain there.

Install from source

Requires OpenCode >=2.0.25 <3 and Node.js/npm for dependency installation and checks.

mkdir -p ~/src/opencode-plugins
git clone https://github.com/edwardEsmerson/opencode-usage.git ~/src/opencode-plugins/opencode-usage
cd ~/src/opencode-plugins/opencode-usage
npm ci

Add the checkout's absolute directory path to plugins in opencode.jsonc, for example "/home/solan/src/opencode-plugins/opencode-usage". Root index.ts/tui.ts forwarding files support V2's local-directory discovery; npm loading uses package exports. Both load precompiled dist/ JavaScript. Do not point directly at src/index.ts, because that omits automatic TUI discovery. After source changes, run npm run build and restart OpenCode; restart after loading-configuration changes too.

Authentication and behavior

• Reads the active V2 openai integration connection through the server SDK. OpenCode owns token refresh; this plugin does not read legacy auth.json or OPENCODE_AUTH_CONTENT, write credentials, or return tokens to the CLI.
• Preserves OpenAI's ChatGPT usage endpoint and account header (V2 metadata.accountID). The endpoint is unofficial and may reject particular OAuth methods, including newer token-sharing credentials. If it rejects an otherwise working connection, select a Codex OAuth connection in /connect; API keys are unsupported. Live compatibility of every OAuth method is not guaranteed.
• Uses the prompt's selected model, then the active session model, falling back to OpenAI on home. Usage is account-wide and may be shared across models.
• Caches usage in the CLI, deduplicates requests, displays recent cached results immediately, and refreshes in the background. Switching connections discards the cache and closes an open usage dialog so old account data cannot remain visible.

Plugin API

• Pins @opencode/plugin to 2.0.25. Both root and ./tui use V2 Plugin.define({ id, setup }); the legacy ./server export is removed.
• Registers /usage with a lifecycle-scoped reactive keymap layer, and uses V2 dialog/router/model APIs and semantic dialog-surface theme tokens.
• The server registers a narrow, cancellable usage RPC, not a tool. Expected errors are sanitized before crossing the RPC boundary.
• Publishes compiled dist/ JavaScript and TypeScript declarations. Babel applies Solid's universal renderer transform ahead of time: the host skips its runtime TSX transform under node_modules, so raw npm TSX loses reactive rendering. Runtime imports remain unbundled; Solid and OpenTUI are peers shared with the host.
• npm ci, npm test, packing and publishing build automatically through prepare/pretest. The build recursively compiles the adapter/auth/format modules as well as UI components; tsconfig.build.json emits declarations separately.

See the V2 CLI plugin guide and migration guide.

Develop

npm ci
npm run typecheck
npm test
npm run build
npm pack --dry-run

Checks run on Node 24 in CI; OpenTUI 0.5.16 warns that native rendering needs Node >=26.4 or Bun >=1.3. The installed OpenCode host provides its rendering runtime. Development pins OpenTUI 0.5.16 and Solid 1.9.12 to satisfy the published OpenTUI peer contract (the host uses Solid 1.9.15); the seroval override selects the patched release for npm checks.

Tests use fake V2 connections and provider responses, not a live account. They validate compiled package/local entrypoints, command/dialog wiring, OAuth connection resolution, account switches, provider parsing, RPC wire validation, and cancellation-safe caching. A rendering regression runs the compiled plugin with Solid's real client/universal runtime and an in-memory backend: asynchronous Show/For updates, refreshed percentages, cached refresh failures, loading errors, and cleanup must work without remounting. Native rendering still needs a restarted live CLI smoke test of an actual npm installation, not only an extracted package outside node_modules.

Distribution

GitHub hosts the source; npm distributes it as opencode-slash-usage. The similarly named opencode-usage package belongs to another project. Licensed under MIT; never commit OAuth credentials or user OpenCode configuration.