Usage Limits

Show provider quota windows in the OpenCode sidebar and prompt footer.

`@mynameistito/opencode-usage-limits`

Usage Limits reads provider quota APIs and authenticated local CLIs, normalizes their different response shapes, and renders the result in OpenCode’s TUI. It refreshes every 60 seconds by default, with an effective minimum of 15 seconds.

Install

opencode2 plugin add "@mynameistito/opencode-usage-limits@latest" -g

The package contains a TUI entrypoint and a published JSON schema:

@mynameistito/opencode-usage-limits/tui
@mynameistito/opencode-usage-limits/schema

Create ~/.config/opencode/usage-limits.jsonc. A complete annotated example is available in the repository at examples/usage-limits.jsonc.

Minimal configuration

Credentials are discovered from OpenCode auth by default:

{
  "$schema": "https://raw.githubusercontent.com/mynameistito/opencode-plugins/main/packages/opencode-usage-limits/usage-limits.schema.json",
  "providers": {
    "codex": { "enabled": true },
    "zai": { "enabled": true, "authorizationScheme": "raw" },
  },
}

The top-level enabled flag disables the plugin. Each provider’s enabled flag controls fetching. showSidebarBar and showFooterBar control display independently without stopping refreshes.

Providers

OpenAI

ChatGPT/OpenAI rolling windows, daily, weekly, or monthly. Credentials come from OpenCode openai auth, then the Codex auth file. See the OpenAI documentation.

Z.AI

Z.AI Coding Plan token rolling window. Uses OpenCode zai-coding-plan or zai auth, or OC_ZAI_API_KEY. See the Z.AI Coding Plan documentation.

Synthetic

Rolling five-hour and weekly quotas. Uses OpenCode synthetic auth or OC_SYNTHETIC_API_KEY. See the Synthetic documentation.

MiniMax

Token Plan rolling five-hour and weekly windows. Uses MiniMax auth or OC_MINIMAX_TOKEN_PLAN_KEY. See the MiniMax documentation.

Qwen

Aggregate Token Plan credits from the authenticated qwencloud CLI. See the Qwen Code documentation.

OpenCode GO

Rolling, weekly, and monthly usage from OpenCode GO auth or OPENCODE_API_KEY. See the OpenCode GO documentation.

Alibaba Token Plan

Personal Token Plan five-hour and weekly windows from the authenticated Bailian bl CLI (version 1.15.0 or newer). See the Bailian documentation.

Display and window selection

Sidebar rows show provider labels, usage percentages or counts, reset times, and stale data when a refresh fails. The footer selects the active session’s provider and renders a compact primary window.

Supported sidebarWindow values are all, rolling, daily, weekly, monthly, credits, and other. footerWindow accepts auto or one of those values. An unavailable explicit choice falls back to the provider’s automatic selection, then its first available window.

{
  "refreshIntervalSeconds": 60,
  "showErrors": true,
  "providers": {
    "codex": {
      "enabled": true,
      "label": "Codex",
      "sidebarWindow": "all",
      "footerWindow": "auto",
      "showSidebarBar": true,
      "showFooterBar": true,
    },
  },
}

Alibaba Token Plan

Authenticate the official Bailian CLI once, then enable the adapter:

bl auth login --console --console-site international
bl usage token-plan --console-region ap-southeast-1 --console-site international --output json

{
  "providers": {
    "alibaba-token-plan": {
      "enabled": true,
      "region": "international",
    },
  },
}

Use region: "china" with the domestic console for mainland China. The plugin does not import browser cookies or store CLI credentials. Missing windows are omitted rather than reported as zero.

Credential lookup

Most installations need only enabled: true. Explicit apiKey and authPath overrides exist for environments where auto-discovery is not enough. Provider errors are typed internally and intentionally rendered without tokens or response bodies. After a successful refresh, the last good value remains visible when a later request fails.

Troubleshooting

Confirm the plugin is installed with opencode2 plugin list.
Confirm the provider is enabled in usage-limits.jsonc.
Confirm the OpenCode auth provider matches the mapping above.
For Qwen and Alibaba, confirm the CLI is authenticated and available on the PATH inherited by OpenCode.
If the package is stale, clear its OpenCode cache and restart OpenCode.

Remove-Item -LiteralPath "$HOME\.cache\opencode\packages\@mynameistito\opencode-usage-limits@latest" -Recurse -Force -ErrorAction SilentlyContinue