GitHub - slkiser/opencode-quota: OpenCode quota & tokens usage with zero context window pollution. Supports OpenCode Go, Cursor, GitHub Copilot, OpenAl (Plus/Pro), Kimi Code, Alibaba Coding Plan, Chutes Al, Google Antigravity, Z.ai Coding Plan and more.

Quota, usage, and token visibility for OpenCode.

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.

After install:

Restart OpenCode.
Run /quota_status.
Run /quota.
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"],
}

All quota settings live in opencode.json or opencode.jsonc, not tui.json.

What It 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
Cursor Auto/Composer and Cursor alias pricing that stays deterministic locally


Popup quota toast	`/tokens_weekly` report

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:

{
  "experimental": {
    "quotaToast": {
      "enabledProviders": ["copilot", "openai", "google-gemini-cli"],
    },
  },
}

Display Options

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

{
  "experimental": {
    "quotaToast": {
      "formatStyle": "allWindows",
    },
  },
}

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

{
  "experimental": {
    "quotaToast": {
      "opencodeGoWindows": ["rolling", "weekly", "monthly"],
    },
  },
}

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

{
  "experimental": {
    "quotaToast": {
      "percentDisplayMode": "used",
    },
  },
}

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

{
  "experimental": {
    "quotaToast": {
      "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 experimental.quotaToast.anthropicBinaryPath in opencode.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:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-gemini-auth", "@slkiser/opencode-quota"],
  "experimental": {
    "quotaToast": {
      "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 experimental.quotaToast.opencodeGoWindows (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:

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

Provider Troubleshooting

Anthropic (Claude)

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 `experimental.quotaToast.anthropicBinaryPath` in `opencode.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.

GitHub Copilot

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

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.

OpenAI

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.

Cursor

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 `experimental.quotaToast.cursorPlan` or `experimental.quotaToast.cursorIncludedApiUsd`.
Billing cycle looks wrong	Set `experimental.quotaToast.cursorBillingCycleStartDay` to your local billing anchor day.
Unknown Cursor pricing	Run `/pricing_refresh`; if still unknown, check `/quota_status` for unknown model ids.

Qwen Code

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`.

Alibaba Coding Plan

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 `experimental.quotaToast.alibabaCodingPlanTier` to `lite` or `pro`.
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`.

MiniMax, Kimi, Chutes AI, Synthetic, Z.ai, and NanoGPT

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.

Google Antigravity

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`.

Gemini CLI

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 `experimental.quotaToast.enabledProviders`.
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`.

OpenCode Go

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 `experimental.quotaToast.opencodeGoWindows` or refresh the dashboard cookie.
Dashboard format changed	This integration scrapes the dashboard, so it can break if the dashboard markup changes.

Token Reports

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 `experimental.quotaToast.pricingSnapshot.source`; `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.

Name		Name	Last commit message	Last commit date
Latest commit History 294 Commits
.github		.github
.husky		.husky
references/upstream-plugins		references/upstream-plugins
scripts		scripts
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.lintstagedrc		.lintstagedrc
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
opencode-quota-logo-dark.svg		opencode-quota-logo-dark.svg
opencode-quota-logo-light.svg		opencode-quota-logo-light.svg
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Installation

Manual Setup

What It Adds

Providers

Display Options

Commands

Anthropic Quick Setup

Companion Providers

Cursor

Qwen Code

Google Antigravity

Gemini CLI

OpenCode Go

Troubleshooting

Provider Troubleshooting

License

Remarks

Star History

About

Uh oh!

Releases 50

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Installation

Manual Setup

What It Adds

Providers

Display Options

Commands

Anthropic Quick Setup

Companion Providers

Cursor

Qwen Code

Google Antigravity

Gemini CLI

OpenCode Go

Troubleshooting

Provider Troubleshooting

License

Remarks

Star History

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 50

Contributors

Uh oh!

Languages