Usage

An OpenCode TUI plugin that shows your active provider's usage limits and remaining credit directly in the sidebar.

Follows whichever provider the current session is using, so the numbers you see are the ones that matter right now — refreshed before you start a query.

• opencode-go — rolling 5h / weekly / monthly usage limits as thin colored bars
• github-copilot — monthly premium requests / chat / completions quota from api.github.com
• deepseek — remaining API credit
• openrouter — remaining credit balance
• openai — remaining API credit balance

Usage limits
OpenCode Go              updated just now
5h      ━━━━━━━━    78%        in 55m
Week    ━━━━        37%        in 2d 2h
Month   ━━          18%        in 27d 15h

Limit bars are colored by severity: green <50%, amber 50–74%, orange 75–99%, red 100%. Credit balances show in green while the account is usable, red when not. Labels, bars, percentages, and reset countdowns use fixed-width columns so usage updates and multiple windows stay aligned. in … is the time until that quota resets.

Requirements

• OpenCode >= 2.0.0 (V2 plugin API)

Install

opencode plugin add opencode-plugin-usage

That installs the TUI plugin and registers it in ~/.config/opencode/cli.json. Keys are picked up automatically (see API keys).

Any options go in the cli.json entry:

{
  "plugins": [
    {
      "package": "opencode-plugin-usage",
      "options": { "providers": { "opencode-go": { "enabled": true } } }
    }
  ]
}

Local development

git clone https://github.com/lhw/opencode-plugin-usage
cd opencode-plugin-usage
npm install
npm run typecheck    # tsc --noEmit
npm test             # parser + rendered layout checks (Node >=26.4)
npm run build        # esbuild → dist/tui.js

OpenCode loads CLI plugins as packages from cli.json, so to try a local build publish a prerelease (or serve npm pack output from a local registry) and run opencode plugin add opencode-plugin-usage.

The plugin must NOT live in ~/.config/opencode/plugins/ — that directory is scanned for server plugins, and opencode rejects this TUI-only module there. TUI plugins are loaded from cli.json.

Configuration

All options are optional. They go in the options object of the plugin's cli.json entry:

{
  "plugins": [
    {
      "package": "opencode-plugin-usage",
      "options": {
        "refreshMs": 300000,       // how often to re-fetch usage (ms)
        "minRefreshMs": 30000,     // minimum interval between extra refreshes (ms)
        "timeoutMs": 10000,        // per-request timeout (ms)
        "default": "opencode-go",  // provider shown when the active provider has no usage source
        "providers": {
          "opencode-go": { "enabled": true },              // apiKey is optional, see below
          "deepseek": { "enabled": true, "apiKey": "sk-…" }
        }
      }
    }
  ]
}

Option	Default	Description
enabled	true	show/hide this provider
apiKey	resolved automatically	explicit key override

API keys

For providers other than OpenAI, credentials resolve from OpenCode in this order:

1. providers.<id>.apiKey in the plugin options
2. OPENCODE_AUTH_CONTENT (opencode's injectable auth file)
3. active OpenCode credential (V2 SQLite credential store)
4. legacy auth.json in OpenCode's data directory
5. the provider's env var (see table below)

So if you've already connected a provider in opencode (opencode auth login or /connect), no extra configuration is needed.

OpenAI Codex uses the OpenCode OAuth access token and account ID for Codex subscription limits. An OpenAI Platform API key (OPENAI_API_KEY or providers.openai.apiKey) cannot access those limits and is not used.

Provider	Credential source
opencode-go	OPENCODE_API_KEY
github-copilot	GITHUB_TOKEN (GH_TOKEN also)
deepseek	DEEPSEEK_API_KEY
openrouter	OPENROUTER_API_KEY
openai	OpenCode OAuth login

Providers

Provider	Source	Display
opencode-go	https://opencode.ai/zen/go/v1/usage	5h/week/month windows + bars
github-copilot	https://api.github.com/copilot_internal/user	premium/chat/completions + bars
deepseek	https://api.deepseek.com/user/balance	remaining credit
openrouter	https://openrouter.ai/api/v1/credits	remaining credit (credits − usage)
openai	https://chatgpt.com/backend-api/wham/usage	Codex 5h + weekly quota windows

Adding a provider is one new file in src/providers/ implementing the Provider interface (key resolution + a fetchUsage) and adding it to the providers array in src/tui.ts.

How it works

• A Plugin.define TUI plugin (@opencode/plugin/tui) that renders into the sidebar.content slot via @opentui/solid.
• Detects the active provider from the last assistant message's model.providerID, falling back to opencode's configured default model.
• Refreshes before you query: on startup, on new session, when a session goes busy, on session.idle, and every refreshMs. Extra triggers are throttled to at most one fetch per minRefreshMs, so balance/usage stays fresh without hammering the APIs.
• Self-heals if data is missing (e.g. after loading an existing session): a signal-driven repaint + a 5-second check re-fetch until data is shown.

Development

npm run typecheck    # tsc --noEmit
npm test             # parser + rendered layout checks (Node >=26.4)
npm run build        # esbuild → dist/tui.js
npm publish          # runs typecheck + build + test first

License

MIT