opencode-usage-report

See how much of your AI subscriptions you have left, right inside opencode.

Adds a /usage dialog, a sidebar panel and a usage_report tool that show your plan's quota windows and how full the current session's context is.

Context
Kimi K2 (High) · 42,318 / 200,000 tokens (21.2%)
Auto-compacts at 180,000 · 137,682 headroom        $0.42 spent

Kimi Code (kimi.ai)
5h limit      █████████░░░░░ 62% resets in 2h 14m
Weekly limit  ████░░░░░░░░░░ 31% resets in 4d 6h

GitHub Copilot
Monthly limit ██░░░░░░░░░░░░ 12% resets in 18d 3h

Features

• Quota windows with progress bars and reset countdowns
• Context breakdown by category, with auto-compaction headroom and session cost
• /usage runs locally and costs no model tokens
• Low-quota toasts in the TUI
• Disk cache, with a local estimate when a provider API is unreachable

Supported providers

| Provider | ID | Usage API | | -------------------- | ----------------------- | ---------------- | | Kimi Code (kimi.ai) | kimi-code-plan-global | api.kimi.ai | | Kimi Code (kimi.com) | kimi-code-plan-cn | api.kimi.com | | OpenCode Go | opencode-go | opencode.ai | | GitHub Copilot | github-copilot | api.github.com | | ChatGPT | openai | chatgpt.com |

Installation

Requires opencode 1.18.29 or later, including 2.x.

opencode plugin -g opencode-usage-report

Omit -g to install for the current project only. Restart opencode afterwards.

The plugin has two entrypoints, so add it to both config files:

// opencode.json: usage_report tool, low-quota warnings
{ "plugin": ["opencode-usage-report"] }

// tui.json: /usage dialog, sidebar panel
{ "plugin": ["opencode-usage-report"] }

Use the bare package name in both files. A subpath such as opencode-usage-report/tui silently loads nothing.

Usage

/usage

Opens the report dialog. Providers without a credential are skipped.

| Key | Action | | ----- | ------------------------ | | r | Refresh now | | tab | Cycle provider scope | | j | Toggle the raw JSON view | | esc | Close |

Press ctrl+shift+u to refresh the sidebar panel.

usage_report tool

The same report for agents and headless runs.

| Argument | Type | Description | | ---------- | --------- | ---------------------------------- | | provider | string | Report one provider, by exact ID | | json | boolean | Return raw ProviderReport[] JSON | | refresh | boolean | Bypass the disk cache |

Context accuracy

• Exact: the total, percentage, free space, compaction point and cost. The total is the prompt size (input + cache.read + cache.write), so it reads slightly lower than opencode's own sidebar, which also counts the completion.
• Estimated: the per-category rows, because opencode records no per-message token counts. They use characters / 4, then scale to match the exact total.
• (derived): the system prompt size could not be measured, so the row is the remainder of the total.

Configuration

Pass options with the tuple form. Each entrypoint reads its own options, so set them in opencode.json, tui.json, or both.

{
  "plugin": [["opencode-usage-report", { "thresholdPercent": 75 }]],
}

| Option | Type | Default | Entrypoint | Description | | ------------------------ | ------------------ | ------- | ---------- | ----------------------------------------------------------- | | thresholdPercent | number | 80 | both | Warn when a window reaches this percentage | | cacheTtlSeconds | number | 120 | both | How long a cached API result stays fresh | | providers | string[] \| null | null | both | Providers to report; null means all | | fallback | boolean | true | server | Use a local estimate when the API fails and no cache exists | | refreshIntervalSeconds | number | 60 | TUI | Refresh cadence, clamped to 5–3600 | | barWidth | number | 14 | TUI | Progress bar width in cells, clamped to 4–40 |

Invalid values are ignored and the default is kept.

Credentials and privacy

Run opencode auth login to sign in. The plugin reads credentials in this order:

1. OPENCODE_USAGE_<ID>_KEY, where <ID> is the provider ID in uppercase with non-alphanumeric characters replaced by _, for example OPENCODE_USAGE_KIMI_CODE_PLAN_GLOBAL_KEY. For ChatGPT, also set OPENCODE_USAGE_OPENAI_ACCOUNT_ID.
2. ~/.local/share/opencode/auth.json. Set $OPENCODE_DATA_HOME to use another data directory.

Keys are never logged, cached or rendered, and adapter errors are redacted before output. The plugin contacts only the usage APIs listed above. Cached reports and plugin state live in <data-home>/usage-report/, and the local estimate reads opencode.db read-only. The plugin stores the size of your system prompt, never its text.

Troubleshooting

/usage is missing. The command comes from the TUI entrypoint. Check that tui.json lists the bare package name, then restart opencode. Running opencode plugin opencode-usage-report should print Detected server + tui targets.

No providers are reported. No credential could be resolved. Run opencode auth login or set OPENCODE_USAGE_<ID>_KEY.

An old version keeps loading. opencode caches packages in ~/.cache/opencode/packages/<name>@latest/. Re-run opencode plugin opencode-usage-report or delete that directory.

Numbers show (stale) or (est). (stale) is a cached result past its TTL. (est) is a local estimate used because the API was unreachable. Press r in the dialog to refetch.

Contributing

See CONTRIBUTING.md for development setup and adding a provider, and CHANGELOG.md for release history. Report vulnerabilities as described in SECURITY.md.

License

MIT © Kaan Chinar