Installation (automatic setup)

npx @slkiser/opencode-quota init

[!IMPORTANT] OpenCode >= 1.4.3 and Node.js >= 18 are required.

The installer is append-only and preserves existing config values. It asks where to install, which quota UI to enable, whether providers should be auto-detected, which quota display style to use, how percentages should be labeled, and whether session input/output tokens should appear in quota displays. By default it writes quota settings to opencode-quota/quota-toast.json only; if you also need the legacy OpenCode experimental.quotaToast block, run npx @slkiser/opencode-quota init --sync-legacy-config.

After install:

1. Restart OpenCode.
2. Run /quota_status.
3. Run /quota.
4. If you enabled the sidebar, open the session sidebar and confirm the Quota panel appears.

For a terminal-only quota glance:

npx @slkiser/opencode-quota show
# or, if installed/on PATH:
opencode-quota show --provider copilot

show is quota-only: no token/cost reports or models.dev refresh. Installer None (commands and terminal only) disables toast/sidebar but keeps /quota, /tokens_*, and terminal show.

Manual setup

Add the server plugin to opencode.json or opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@slkiser/opencode-quota"],
}

If you also want the sidebar, add the same package to the tui.json or tui.jsonc file that OpenCode loads:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["@slkiser/opencode-quota"],
}

Quota settings live in opencode-quota/quota-toast.json next to the OpenCode config file chosen by the installer (project or global). On load, OpenCode Quota reads that sidecar first and falls back to existing experimental.quotaToast settings in opencode.json / opencode.jsonc only when the sidecar is absent. Normal runtime/load does not create, re-add, or migrate experimental.quotaToast; use init --sync-legacy-config when you explicitly want the installer to also write/sync that legacy block. Quota settings do not live in tui.json.

What plugin adds

• TUI sidebar panel with quota rows
• Popup quota toasts after assistant responses
• Manual /quota, /quota_status, and /tokens_* commands
• Terminal opencode-quota show command for a quota-only quick glance
• Local token reports using bundled and runtime models.dev pricing
• Custom quota tracking for companion plugins

Providers

| Provider | Auto setup? | Setup / plugin order | Quota source | | ----------------------- | ------------------ | --------------------------------------------------------- | ------------------------ | | Anthropic (Claude) | Needs quick setup | Install and authenticate Claude CLI | Local CLI or OAuth usage | | GitHub Copilot | Usually automatic | Existing OpenCode auth, or optional PAT config | Remote API | | OpenAI | Automatic | Existing OpenCode auth | Remote API | | Cursor | Needs quick setup | ["@playwo/opencode-cursor-oauth", "@slkiser/opencode-quota"] | Local estimation | | Qwen Code | Needs quick setup | ["opencode-qwencode-auth", "@slkiser/opencode-quota"] | Local estimation | | Alibaba Coding Plan | Automatic | Existing OpenCode auth, global config, or env | Local estimation | | MiniMax Coding Plan | Automatic | Existing OpenCode auth, global config, or env | Remote API | | Kimi Code | Automatic | Existing OpenCode auth, global config, or env | Remote API | | Chutes AI | Usually automatic | Existing OpenCode auth, global config, or env | Remote API | | Synthetic | Automatic | Existing OpenCode auth, global config, or env | Remote API | | Google Antigravity | Needs quick setup | ["opencode-antigravity-auth", "@slkiser/opencode-quota"] | Remote API | | Gemini CLI | Needs quick setup | ["opencode-gemini-auth", "@slkiser/opencode-quota"] | Remote API | | Z.ai Coding Plan | Automatic | Existing OpenCode auth, global config, or env | Remote API | | NanoGPT | Usually automatic | Existing OpenCode auth, global config, or env | Remote API | | OpenCode Go | Needs quick setup | Set workspace ID and auth cookie | Dashboard scraping |

For companion auth providers, put the companion plugin first and @slkiser/opencode-quota second. The companion plugin handles login or token storage; OpenCode Quota reads that auth state and renders quota.

Providers are auto-detected by default. To choose providers explicitly:

// opencode-quota/quota-toast.json
{
  "enabledProviders": ["copilot", "openai", "google-gemini-cli"],
}

Display options

Show every quota window instead of the default most-constrained window:

// opencode-quota/quota-toast.json
{
  "formatStyle": "allWindows",
}

Choose which OpenCode Go usage windows to display (default is all three; rolling displays as 5h):

// opencode-quota/quota-toast.json
{
  "opencodeGoWindows": ["rolling", "weekly", "monthly"],
}

Show percentages as used instead of remaining in toasts and the sidebar:

// opencode-quota/quota-toast.json
{
  "percentDisplayMode": "used",
}

Turn off popup toasts while keeping /quota and the sidebar:

// opencode-quota/quota-toast.json
{
  "enableToast": false,
}

Commands

| Command | What it shows | | --------------------- | -------------------------------------------------- | | opencode-quota show | Terminal quota-only quick glance | | /quota | Detailed quota report | | /quota_status | Config, provider, auth, pricing, and live probes | | /pricing_refresh | Refresh local runtime pricing from models.dev | | /tokens_today | Tokens used today | | /tokens_daily | Tokens used in the last 24 hours | | /tokens_weekly | Tokens used in the last 7 days | | /tokens_monthly | Tokens used in the last 30 days, including pricing | | /tokens_all | Tokens used across all local history | | /tokens_session | Tokens used in the current session | | /tokens_session_all | Current session plus descendant sessions | | /tokens_between | Tokens used between YYYY-MM-DD YYYY-MM-DD |

Anthropic quick setup

Anthropic does not use a companion OpenCode plugin. Install Claude Code, authenticate it, and make sure claude is available on your PATH:

claude auth login
claude auth status

If Claude lives at a custom path, set anthropicBinaryPath in opencode-quota/quota-toast.json.

Companion providers

Some providers need an auth companion plugin installed separately. Add the companion plugin first and @slkiser/opencode-quota second in opencode.json or opencode.jsonc.

Cursor

Companion plugin: @playwo/opencode-cursor-oauth

Add both plugins to opencode.json, with the Cursor auth plugin first:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@playwo/opencode-cursor-oauth", "@slkiser/opencode-quota"],
  "provider": {
    "cursor": {
      "name": "Cursor"
    }
  }
}

Then authenticate Cursor once:

opencode auth login --provider cursor

Qwen Code

Companion plugin: opencode-qwencode-auth

Add both plugins to opencode.json, with the Qwen auth plugin first:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-qwencode-auth", "@slkiser/opencode-quota"]
}

Google Antigravity

Companion plugin: opencode-antigravity-auth

Add both plugins to opencode.json, with the Antigravity auth plugin first:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-antigravity-auth", "@slkiser/opencode-quota"]
}

Gemini CLI

Companion plugin: opencode-gemini-auth

Add both plugins to opencode.json, with the Gemini auth plugin first. If you manually choose providers, include google-gemini-cli in opencode-quota/quota-toast.json:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-gemini-auth", "@slkiser/opencode-quota"]
}

// opencode-quota/quota-toast.json
{
  "enabledProviders": ["google-gemini-cli"]
}

Then authenticate Google once:

opencode auth login --provider google

OpenCode Go

OpenCode Go quota scrapes the dashboard and needs a workspace ID plus an auth cookie:

export OPENCODE_GO_WORKSPACE_ID="your-workspace-id"
export OPENCODE_GO_AUTH_COOKIE="your-auth-cookie"

The provider can report three usage windows — 5h rolling, Weekly, and Monthly — and emits whichever dashboard windows are available in that order. Filter displayed windows with opencodeGoWindows in opencode-quota/quota-toast.json (rolling, weekly, monthly); non-default subsets report missing selected dashboard fields, while default/all-windows mode shows available windows and diagnostics indicate what was found.

Environment variables take precedence over the optional opencode-go.json config file. Run /quota_status to see the exact paths checked on your machine.

Troubleshooting

If quota or token data looks wrong:

1. Run /quota_status.
2. Confirm the expected provider appears in the detected provider list.
3. Confirm OpenCode has already created opencode.db if token reports are empty.
4. Check companion plugins for Cursor, Qwen Code, Google Antigravity, and Gemini CLI.
5. Use the quick-setup link in the provider table for provider-specific auth and config notes.

Provider Troubleshooting

Run /quota_status and check the Anthropic section.

| Symptom | Fix | | --- | --- | | claude not found | Install Claude Code and make sure claude is on your PATH. | | Claude is installed at a custom path | Set anthropicBinaryPath in opencode-quota/quota-toast.json. | | Not authenticated | Run claude auth login, then confirm claude auth status works. | | Auth works but no quota rows appear | Check quota_source and message in /quota_status; re-authenticate Claude if the OAuth credential fallback is missing or stale. | | Provider not detected | Confirm OpenCode is configured to use the anthropic provider. |

Run /quota_status and check copilot_quota_auth, billing_mode, billing_scope, and quota_api.

For personal Copilot OAuth quota, the plugin uses GitHub's reported premium-interaction quota fields when available. If that specific quota payload marks premium interactions as unlimited, quota output renders Unlimited instead of a synthetic used/total ratio.

| Symptom | Fix | | --- | --- | | Personal quota missing | Confirm OpenCode Copilot auth works. The plugin can read OpenCode's Copilot OAuth token. | | Business or Enterprise quota missing | Add copilot-quota-token.json in the OpenCode runtime config directory shown by opencode debug paths. | | PAT config exists but quota fails | Fix copilot-quota-token.json; when present, it takes precedence over OAuth and does not silently fall back. | | Enterprise usage missing | Use a classic PAT with the required billing access. Fine-grained PATs and GitHub App tokens are not supported for Enterprise premium usage. |

Run /quota_status and check the OpenAI auth source and token status.

| Symptom | Fix | | --- | --- | | OpenAI quota missing | Confirm OpenCode native OpenAI auth is present in auth.json. | | Token expired | Re-run OpenCode's OpenAI auth flow. | | Provider not detected | Confirm your OpenCode config uses the openai provider or a compatible OpenAI auth entry. |

Run /quota_status and check the Cursor section.

| Symptom | Fix | | --- | --- | | Cursor not detected | Put @playwo/opencode-cursor-oauth before @slkiser/opencode-quota in opencode.json. | | Cursor auth missing | Run opencode auth login --provider cursor. | | Quota appears but no remaining percentage | Set cursorPlan or cursorIncludedApiUsd in opencode-quota/quota-toast.json. | | Billing cycle looks wrong | Set cursorBillingCycleStartDay in opencode-quota/quota-toast.json to your local billing anchor day. | | Unknown Cursor pricing | Run /pricing_refresh; if still unknown, check /quota_status for unknown model ids. |

Run /quota_status and check qwen_oauth_source, qwen_local_plan, and the qwen_code live probe section.

| Symptom | Fix | | --- | --- | | Qwen not detected | Put opencode-qwencode-auth before @slkiser/opencode-quota in opencode.json. | | Auth missing | Complete the Qwen companion plugin auth flow. | | Counters do not move | Confirm the current model is qwen-code/*; Qwen quota is local request estimation for matching model usage. | | Usage looks stale | Check the local state file path shown by /quota_status. |

Run /quota_status and check the Alibaba auth, resolved tier, state-file path, and alibaba_coding_plan live probe section.

| Symptom | Fix | | --- | --- | | API key not detected | Use ALIBABA_CODING_PLAN_API_KEY, ALIBABA_API_KEY, trusted user/global OpenCode config, or OpenCode auth. Repo-local provider secrets are ignored. | | Wrong tier | Set alibabaCodingPlanTier to lite or pro in opencode-quota/quota-toast.json. | | Counters do not move | Confirm the current model is alibaba/* or alibaba-cn/*. | | Quota seems stale | Check the state-file path shown in /quota_status. |

These providers use trusted env vars, trusted user/global OpenCode config, or native OpenCode auth. Run /quota_status and check the provider-specific API-key diagnostics.

| Provider | Useful checks | | --- | --- | | MiniMax Coding Plan | Use MINIMAX_CODING_PLAN_API_KEY or MINIMAX_API_KEY; repo-local provider secrets are ignored. | | Kimi Code | Use KIMI_API_KEY or KIMI_CODE_API_KEY; repo-local provider secrets are ignored. | | Chutes AI | Use CHUTES_API_KEY or trusted user/global config. | | Synthetic | Use SYNTHETIC_API_KEY, trusted user/global config, or OpenCode auth. | | Z.ai Coding Plan | Use ZAI_API_KEY or ZAI_CODING_PLAN_API_KEY; malformed fallback auth is surfaced as an auth error. | | NanoGPT | Use NANOGPT_API_KEY, NANO_GPT_API_KEY, trusted user/global config, or OpenCode auth. |

For security, repo-local opencode.json / opencode.jsonc is ignored for provider secrets in these integrations. Put secrets in environment variables or trusted user/global config.

Run /quota_status and check the google_antigravity section.

| Symptom | Fix | | --- | --- | | Companion missing | Put opencode-antigravity-auth before @slkiser/opencode-quota in opencode.json. | | Accounts not found | Check the selected antigravity-accounts.json path shown by /quota_status. | | Refresh tokens invalid | Re-authenticate with the companion plugin. | | Provider returns no rows | Check live_probe, live_entry_*, and live_error_* in /quota_status. |

Run /quota_status and check the Gemini CLI live probe rows.

| Symptom | Fix | | --- | --- | | Companion missing | Put opencode-gemini-auth before @slkiser/opencode-quota in opencode.json. | | Provider not enabled in manual mode | Include google-gemini-cli in enabledProviders in opencode-quota/quota-toast.json. | | Auth missing | Run opencode auth login --provider google. | | Project missing | Set provider.google.options.projectId, OPENCODE_GEMINI_PROJECT_ID, GOOGLE_CLOUD_PROJECT, or GOOGLE_CLOUD_PROJECT_ID. |

Run /quota_status and check the opencode_go section.

| Symptom | Fix | | --- | --- | | Config not detected | Set both OPENCODE_GO_WORKSPACE_ID and OPENCODE_GO_AUTH_COOKIE, then rerun /quota_status. | | Incomplete config | workspaceId and authCookie must come from the same source. | | Scrape returns no data | Refresh the browser auth cookie from opencode.ai. | | Selected window missing | Check /quota_status for selected_windows and live_fetch_error; remove unavailable windows from opencodeGoWindows in opencode-quota/quota-toast.json or refresh the dashboard cookie. | | Dashboard format changed | This integration scrapes the dashboard, so it can break if the dashboard markup changes. |

Run /quota_status and check pricing snapshot health plus OpenCode database paths.

| Symptom | Fix | | --- | --- | | /tokens_* is empty | Start OpenCode once so it creates opencode.db, then run a session with model usage. | | Pricing looks stale | Run /pricing_refresh. | | Runtime pricing does not change output | Check pricingSnapshot.source in opencode-quota/quota-toast.json; bundled keeps packaged pricing active. | | Cursor model has unknown pricing | Run /pricing_refresh; Cursor auto and composer* use bundled deterministic pricing. |

License

MIT

Remarks

OpenCode Quota is not built by the OpenCode team and is not affiliated with OpenCode or any provider listed above.

Star History