opencode-usage-quota

OpenCode TUI plugin for Codex quota and clearly labeled provider-usage visibility.

What it reports

• Codex remote quota: five-hour and weekly windows when the running OpenCode build exposes experimental.console.codexQuota.

• Other providers: rolling five-hour and weekly local token usage observed from OpenCode assistant messages.

• Provider-quota framework handoff: the standalone plugin track can show stock-OpenCode detail views today; the native OpenCode PR track owns exact prompt-metrics placement and server-side provider auth access.

• exact — current remaining quota from a provider-owned or OpenCode-owned quota source.

• reported — official limits or response/header values that are current but may not cover every provider window.

• estimated — local usage or heuristics only; never shown as enforced remaining quota in the compact prompt.

Compact prompt output only includes exact and reported windows. Estimated local usage is available in details so it cannot be mistaken for real provider quota.

Two install modes

Stock OpenCode plugin mode

Use this mode for released OpenCode builds that do not include native provider quota support. The plugin:

• fetches Codex quota through OpenCode's safe experimental Codex quota helper/route when available;
• renders its own compact Codex status under the prompt rows;
• keeps local provider token/cost windows in the /quota detail view only; and
• labels local provider data as usage, not exact quota.

Native OpenCode provider-quota mode

Use this mode for a locally patched or future upstream OpenCode build that exposes native provider quota state, such as GET /experimental/provider-quota and prompt metrics beside the built-in context/cost line.

The native OpenCode track should own compact prompt placement. In that mode, this plugin should remain useful for /quota details and QA, but avoid rendering a duplicate compact quota row when native provider quota is visibly present.

Easy install

The recommended install path is OpenCode's built-in plugin installer. It installs the GitHub package and updates your TUI plugin config automatically.

Install globally for every OpenCode project:

opencode plugin github:50sotero/opencode-usage-quota --global

Or install only for the current project:

opencode plugin github:50sotero/opencode-usage-quota

Restart OpenCode after installing. You should see the compact quota/session row below the chat box, and /quota plus /dashboard should appear in the command palette.

If you previously installed an early version of this repo and OpenCode added it to opencode.json(c), remove that old server-plugin entry and run the command above again. This package now advertises only its ./tui entrypoint, so the OpenCode installer writes it to tui.json(c) instead of treating it as a server plugin.

Manual install fallback

Use this if your OpenCode build does not have the opencode plugin command yet. Add the plugin to your TUI config:

• Global: ~/.config/opencode/tui.jsonc
• Project: .opencode/tui.jsonc

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["github:50sotero/opencode-usage-quota"]
}

Local development install

When hacking on this repo, point OpenCode directly at the local TUI entrypoint:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [["/absolute/path/to/opencode-usage-quota/src/tui.tsx", { "refreshMs": 60000, "glyphs": "unicode" }]]
}

glyphs defaults to unicode; set it to ascii only if a terminal has broken glyph-width handling.

UI surfaces

• Compact Codex status below session_prompt and in home_bottom for stock OpenCode plugin mode.
• Session metrics are appended to the compact row after a session has token data: context usage, total session tokens, and updated HH:MM:SS.
• Command palette entries and slash commands:
  • /quota — provider quota and local usage detail.
  • /dashboard — current-session dashboard with token buckets, context usage, quota windows, and data-source labels.
• Native-aware guard: if OpenCode exposes generated native provider-quota helpers, this plugin keeps the detail command but does not render a duplicate compact prompt row.

Example compact status:

Codex · 5h █████████░ 88% · wk █████████░ 94% · updated 13:05:42

After a prompted session:

Codex · 5h █████████░ 88% · wk █████████░ 94% · updated 13:05:42 · ctx 19.9K/400K 5% · tok 22.4K

Fallback when Codex remote quota is unavailable:

codex quota unavailable

The /quota dialog is where local provider usage appears:

Local OpenCode usage, not provider-enforced quota:
- anthropic/claude-sonnet: 5h 1,250,000 tokens, wk 9,500,000 tokens

The /dashboard dialog is per-session and labels observed/local values separately from provider-enforced quota:

Session dashboard

Quota
Codex      5h   █████████░ 88% left
Codex      wk   █████████░ 94% left

Current session
Input       19,858
Output      7
Reasoning   23
Cache read  2,560
Total       22,448
Updated     13:05:42

Context
Used        19,858 / 400,000 (5%)
Usage       █░░░░░░░░░
Source      observed assistant input tokens

Screenshots

Compact quota row on the home screen

Compact session metrics below the chat box

/dashboard session detail view

Provider support and confidence labels

Quota data must carry one of these confidence labels:

• exact — the provider or OpenCode reports current remaining quota and reset windows.
• reported — an official API, configured limit, or response header reports limits/remaining values, but not necessarily the full long-window quota picture.
• estimated — inferred from local counters, warnings, or heuristics. Estimated data belongs in detail views and must not be presented as exact remaining quota.

Provider	Current plugin data	Confidence	Compact stock-plugin prompt
Codex / ChatGPT OAuth	Five-hour and weekly remote quota when OpenCode exposes the safe Codex endpoint	exact	Yes
OpenAI API key	Local OpenCode token/cost usage only; not the same quota pool as ChatGPT Codex	estimated	No
Anthropic	Local usage today; future adapters may consume official rate-limit headers	estimated today, reported when header-backed	No for estimated-only data
Gemini / Google	Local usage today; future adapters may report documented project/model limits	estimated today, reported for documented limits	No for estimated-only data
GitHub Copilot	Local usage today; organization/team metrics are usage visibility, not per-user remaining quota	estimated unless an official current source exists	No
OpenRouter / compatible providers	Local usage today; provider-specific APIs or response headers may be added later	estimated today, provider-specific later	No for estimated-only data

The official OpenCode PR track should reuse the same exact | reported | estimated vocabulary so native prompt metrics and plugin detail views tell the same truth.

See docs/provider-quota-evidence.md for the official-source evidence matrix that gates future provider adapters and upstream PR language.

Development

bun install
bun test
bun run typecheck
bun run build