Skip to content
mynameistito / plugins
Esc
↑↓navigate↵open⌘Jpreview
On this page

Usage Limits

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

@mynameistito/opencode-usage-limits

Release history: Usage Limits changelog.

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

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.

Command Code

Rolling five-hour and weekly windows from the Command Code billing API, with monthly usage derived from the current credit balance and usage summary. The monthly window is shown as unknown when its summary cannot be read. Organization accounts are scoped using the identity returned by /alpha/whoami; personal accounts use unscoped requests. Command Code’s rolling 5-hour window can also appear in the prompt footer.

Credentials are discovered from OpenCode auth for the commandcode provider. As a fallback, configure apiKey (for example, {env:COMMANDCODE_API_KEY}):

{
  "providers": {
    "commandcode": {
      "enabled": true,
      "apiKey": "{env:COMMANDCODE_API_KEY}", // Optional fallback
    },
  },
}

DeepSeek

DeepSeek exposes a current account balance rather than a rolling or monthly usage quota. The provider reads the official GET /user/balance endpoint and displays each reported currency independently, for example $12.34 remaining for USD.

Enable it with the DeepSeek key already saved by OpenCode, or configure an explicit key:

{
  "providers": {
    "deepseek": {
      "enabled": true,
      "apiKey": "{env:DEEPSEEK_API_KEY}",
    },
  },
}

The adapter uses total_balance directly. It does not add granted_balance and topped_up_balance, combine currencies, or invent a percentage/reset time. OpenCode-discovered credentials are sent only to https://api.deepseek.com; a custom baseUrl requires an explicit authPath or apiKey.

MiniMax

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

Moonshot/Kimi API

Moonshot/Kimi Open Platform is a pay-as-you-go API balance, separate from Kimi For Coding’s subscription-based 5-hour and weekly quota. Choose the provider matching the region where the API key was created:

Provider ID Official balance endpoint Currency OpenCode auth ID
moonshotai https://api.moonshot.ai/v1/users/me/balance USD moonshotai
moonshotai-cn https://api.moonshot.cn/v1/users/me/balance CNY moonshotai-cn

The adapter displays data.available_balance directly as the remaining balance. It does not recompute cash plus voucher balances, convert the amount to a percentage, or infer a reset time. Zero and negative balances remain visible. The response must have code: 0, status: true, and a finite numeric data.available_balance; malformed or unsuccessful responses fail closed.

Enable either region with the matching OpenCode auth entry, or provide an explicit key:

{
  "providers": {
    "moonshotai": {
      "enabled": true,
      "apiKey": "{env:MOONSHOT_API_KEY}", // Optional global key
    },
    "moonshotai-cn": {
      "enabled": true,
      "apiKey": "{env:MOONSHOT_API_KEY_CN}", // Optional China key
    },
  },
}

Global and China keys are independent and are never sent to the other region. OpenCode-discovered credentials are sent only to the exact corresponding official origin. A custom baseUrl requires an explicitly configured authPath or apiKey.

Novita AI

Displays the current available API balance as a remaining USD amount, not a monthly usage window. Novita’s official GET /openapi/v1/billing/balance/detail endpoint returns monetary fields in 1/10,000 USD units; the plugin converts availableBalance to USD and does not infer a percentage, balance total, or reset time.

Enable the novita-ai provider using OpenCode’s saved credential, or configure a key explicitly:

{
  "providers": {
    "novita-ai": {
      "enabled": true,
      "apiKey": "{env:NOVITA_API_KEY}",
    },
  },
}

OpenCode credentials are only sent to https://api.novita.ai; a custom baseUrl requires an explicit authPath or apiKey.

OpenRouter

Displays the current OpenRouter API key’s finite spending limit from the official GET /api/v1/key endpoint. The spend window uses limit and limit_remaining as USD amounts; it is key-level spending-limit usage, not total account balance. daily, weekly, and monthly reset cadences are shown without inferring an absolute reset time. Unbounded or unavailable limits appear as unknown. Deprecated rate_limit and BYOK usage are ignored.

OpenCode’s saved openrouter credential is used automatically, or configure an explicit environment-backed API key:

{
  "providers": {
    "openrouter": {
      "enabled": true,
      "apiKey": "{env:OPENROUTER_API_KEY}", // Optional fallback
    },
  },
}

OpenCode-discovered credentials are sent only to the exact official https://openrouter.ai origin. A custom baseUrl requires an explicit authPath or apiKey.

OpenAI

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

OpenCode GO

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

Qwen

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

Synthetic

Rolling five-hour and weekly quotas. Uses OpenCode synthetic auth or OC_SYNTHETIC_API_KEY. See the Synthetic 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.

Display and window selection

Sidebar rows show provider labels, usage percentages, counts, or remaining balances, 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

  1. Confirm the plugin is installed with opencode2 plugin list.
  2. Confirm the provider is enabled in usage-limits.jsonc.
  3. Confirm the OpenCode auth provider matches the mapping above.
  4. For Qwen and Alibaba, confirm the CLI is authenticated and available on the PATH inherited by OpenCode.
  5. 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
rm -rf ~/.cache/opencode/packages/@mynameistito/opencode-usage-limits@latest

Last updated on

Was this page helpful?