@leo000001/opencode-quota-sidebar
Advanced tools
OpenCode plugin that shows quota and token usage in TUI sidebar panels and compact session titles
OpenCode plugin that shows token usage and provider quota in the TUI sidebar, while keeping the shared session title compact and readable across Desktop, Web, and TUI.
The screenshot above comes from ./assets/OpenCode-Quota-Sidebar.png and shows the actual TUI sidebar layout this plugin renders.
TITLE, USAGE, and QUOTA blocks in the TUI sidebarsession.title on a compact single line instead of pushing multiline telemetry into every clientsession, day, week, and monthquota_summary and quota_show tools for reports and title togglingThis repository is a pure plugin implementation. It does not modify OpenCode core.
QuotaSnapshot shape through a registry of adaptersThe implementation is built on top of @opencode-ai/plugin and @opencode-ai/sdk.
This plugin has two display layers:
TITLE, USAGE, and QUOTA blocksIn sidebar.titleMode="auto", the shared title remains a compact single line. The richer multiline layout is handled by the dedicated TUI plugin instead of being written into session.title for every client.
Session-scoped aggregation can include descendant subagent sessions when sidebar.includeChildren=true. Day/week/month summaries do not merge descendants.
Built-in quota adapters:
| Provider | Endpoint family | Auth | Quota shape | Notes |
|---|---|---|---|---|
| OpenAI Codex | chatgpt.com/backend-api/wham/usage | OAuth | Multi-window subscription | Reads ChatGPT usage windows such as short-term + weekly; Pro plans may also expose Codex Spark limits (additional_rate_limits) |
| GitHub Copilot | api.github.com/copilot_internal/user | OAuth | Monthly subscription | Uses the Copilot internal user endpoint |
| Anthropic | api.anthropic.com/api/oauth/usage | OAuth | Multi-window subscription | Supports plan-based usage windows |
| Kimi For Coding | api.kimi.com/coding/v1/usages | API key | Multi-window subscription | Typically 5h + weekly windows |
| Zhipu Coding Plan | bigmodel.cn/api/monitor/usage/quota/limit | API key | Token quota | Coding-plan style quota window |
| MiniMax Coding Plan | www.minimaxi.com/v1/api/openplatform/coding_plan/remains | API key | Multi-window subscription | Typically 5h + weekly windows |
| RightCode | www.right.codes/account/summary | API key | Daily quota and/or balance | Prefix-based subscription matching, with balance fallback |
Generic providers without a built-in quota endpoint can still contribute usage totals, but they will not show quota/balance unless an adapter exists.
Provider notes:
GPT-5.3-Codex-Spark) in the additional_rate_limits field of the wham/usage response. When present, the plugin automatically parses and renders these as extra windows under the OpenAI quota line. No extra config is required. Code review quota (code_review_rate_limit) is not displayed yet.quota_summary fetches default quota providers even if they were not used in the current sessionsidebarPanel / usage state first, so historical sessions can render quickly on open or resumequota_show toggles title decoration on or off, but the TUI panel remains the main rich display pathOpenCode loads the server plugin from opencode.json and the TUI plugin from tui.json.
opencode.json
{
"plugin": ["@leo000001/opencode-quota-sidebar@latest"]
}
tui.json
{
"plugin": ["@leo000001/opencode-quota-sidebar@latest"]
}
For OpenCode >=1.2.15, keep server plugins in opencode.json and TUI plugins in tui.json.
Typical TUI sidebar layout (with Codex Spark windows):
TITLE
Fix quota adapter matching
USAGE
R184 I189k O53.2k
CR31.4k CW3.2k Cd66%
API $12.8
QUOTA
OAI 5h80 R3h20m
W70 R2D04h
Sk5h100 R1h00m
SkW100 R3D04h
Cop M78 R12D00h
RC D$88.9/$60 E6D00h
B260
Compact shared title example:
Fix quota adapter matching | OAI 5h80 R3h20m W70 R2D04h | RC D$88.9/$60 B260 | Cd66% | API$12.8
API cost is an API-equivalent estimate. It is not your subscription fee, not a provider invoice, and not necessarily what the upstream service actually billed.
Pricing source priority:
opencode.jsonc / opencode.json)provider.list()models.dev remote model catalog pricingImportant notes:
cost: 0, so runtime pricing is only a supplemental sourceprovider.list() is a runtime metadata view of the models OpenCode currently exposes; it is useful when non-zero, but it is not a stable authoritative pricing APIinput / output without discarding earlier cache_* or context_over_200k fieldsmodels.dev is used as a structured remote supplement only for runtime-discovered models that are still missing prices after config, runtime, and bundled sources are considered; this mainly helps newer models that are not in the plugin's bundled table yetmodels.dev is unreachable, the plugin falls back to the higher-priority sources above; API cost may remain 0 for uncovered models until pricing becomes available againAPI cost may stay $0.00 until you add an explicit model price override in your OpenCode main configTo get complete API cost coverage for new models, at least one of these must be true:
provider.list() returns a non-zero price for itprovider.list() exposes the model and models.dev has pricing for itExample historical quota_summary markdown output shape:
## Quota History - Daily since 2026-02-18
### Quota Status
- OpenAI: 5h | 80.0% | reset 3h20m; Weekly | 70.0% | reset 2D04h
- Copilot: Monthly | 78.0% | reset 12D00h
- RightCode: Daily $88.9/$60 | reset 6D00h
### Totals
| Metric | Total | Avg/Period |
| ------------ | ----: | ---------: |
| Requests | 184 | 26.3 |
| Total Tokens | 277k | 39.6k |
| Cache Hit | 63.1% | 58.4% |
| API Cost | $12.8 | $1.83 |
### Provider Breakdown
| Provider | Req | Input | Output | Total | Share | Cache Hit | API Cost |
| --------- | --: | ----: | -----: | ----: | ----: | --------: | -------: |
| OpenAI | 140 | 160k | 61k | 221k | 79.8% | 66.2% | $10.4 |
| Anthropic | 44 | 29k | 27.1k | 56.1k | 20.2% | 51.3% | $2.34 |
### Period Detail
| Period | Requests | Input | Output | Cache | Cache Hit | Total | API Cost |
| ------------ | -------: | ----: | -----: | ----: | --------: | ----: | -------: |
| 2026-02-18 | 12 | 18.3k | 4.2k | 8.9k | 32.7% | 31.4k | $1.12 |
| 2026-02-24\* | 17 | 8.1k | 2.0k | 3.4k | 66.0% | 13.5k | $0.88 |
The tool already returns full markdown. Clients should display that report directly instead of replacing it with a short summary.
Sidebar output uses compact tokens. Toasts and markdown reports keep fuller human-readable wording.
OpenCode renders the sidebar title as plain text inside a single styled title field. That means the shared title is great for compact telemetry, but not ideal for a rich multi-section layout.
This plugin therefore uses:
That split avoids polluting Desktop/Web titles while still giving TUI users a readable quota dashboard.
Usage tokens:
R: requestsI: input tokensO: output tokens, including reasoning tokensCR: cache read tokensCW: cache write tokensCd: cached ratio / cache coverageAPI: API-equivalent cost estimateQuota tokens:
OAI: OpenAICop: GitHub CopilotAnt: AnthropicRC: RightCodeB: balanceD: daily windowW: weekly windowM: monthly windowSk5h: OpenAI Codex Spark short window (e.g. 5h)SkW: OpenAI Codex Spark weekly windowR3h20m: resets in 3h20mR2D04h: resets in 2D04hE6D00h: expires in 6D00hExample compact quota fragments:
OAI 5h80 R3h20m: OpenAI short window, 80% remaining, resets in 3h20mOAI Sk5h100 R1h00m: OpenAI Codex Spark 5h window, 100% remaining, resets in 1h00mOAI SkW100 R3D04h: OpenAI Codex Spark weekly window, 100% remaining, resets in 3D04hCop M78 R12D00h: Copilot monthly quota, 78% remaining, resets in 12D00hRC D$88.9/$60 E6D00h B260: RightCode daily quota plus balanceRecommended config file locations:
~/.config/opencode/quota-sidebar.config.json<worktree>/quota-sidebar.config.json<directory>/quota-sidebar.config.json<worktree>/.opencode/quota-sidebar.config.json<directory>/.opencode/quota-sidebar.config.jsonOPENCODE_QUOTA_CONFIG=/absolute/path/to/config.jsonMinimal example:
{
"sidebar": {
"enabled": true,
"titleMode": "auto",
"showCost": true,
"showQuota": true,
"includeChildren": true
}
}
See quota-sidebar.config.example.json for a fuller config example.
Important config notes:
sidebar.titleMode: auto, compact, or multilinesidebar.showCost: controls API-equivalent cost in sidebar, title, markdown report, toast, and CLI outputsidebar.wrapQuotaLines: wraps long quota lines with indentation instead of dropping fieldssidebar.includeChildren: includes descendant subagent sessions for period=session
Config is layered. The later source overrides the earlier one:.opencode config.opencode configOPENCODE_QUOTA_CONFIGOpenCode main pricing config candidates are read from these locations:
~/.config/opencode/opencode.jsonc~/.config/opencode/opencode.json<worktree>/opencode.jsonc<worktree>/opencode.json<directory>/opencode.jsonc<directory>/opencode.json<worktree>/.opencode/opencode.jsonc<worktree>/.opencode/opencode.json<directory>/.opencode/opencode.jsonc<directory>/.opencode/opencode.jsonopencode-quota auto-starts a temporary opencode serve when no local server is reachable and OPENCODE_BASE_URL is not set127.0.0.1:4096; if that port is busy, the CLI retries on another local port automaticallyexit, SIGINT, SIGTERM, uncaughtExceptionMonitor), and a detached watchdog kills it after 10 minutes if it is somehow left behindopencode serve manually to inspect logs or set OPENCODE_BASE_URLThe plugin stores:
<opencode-data>/quota-sidebar.state.json<opencode-data>/quota-sidebar-sessions/YYYY/MM/DD.jsonThose persisted chunks keep title state, cached usage, sidebar-panel payloads, and quota cache data. This lets the TUI sidebar render from stored structured state on session open/resume instead of depending entirely on live message scans.
Usage aggregation is incremental. The plugin tracks a cursor per session and processes only new messages when possible. If message history changes in a way that invalidates the incremental view, it can rescan and refresh persisted usage.
Pricing cache notes:
pricingFingerprint alongside cached session usageEst$... are recognized during cleanup/restore, but newly rendered titles always use API$...quota_summary: shows usage and quota for session, day, week, or monthquota_show: toggles title decoration on or offBehavior notes:
quota_summary returns the full markdown report bodyquota_summary can show a toast in addition to returning markdownquota_summary accepts period, since, last, toast, and includeChildrenquota_summary(includeChildren=true) only changes period=sessionday/week/month scans all sessions in the selected time range, so child sessions are included when they have activity in that rangeday/week/month does not do parent-tree rollup; child sessions are counted as independent sessions, not merged through includeChildrensince and last are mutually exclusiveperiod=session does not accept since or lastquota_show(enabled=true|false) can explicitly force a state instead of togglingsince and relative lastsince accepts YYYY-MM or YYYY-MM-DDlast accepts a positive integer and is relative to the current period: day=7, week=8, month=6period=day|week|month means the current natural day/week/monthExample command aliases:
For direct in-chat history output, define command aliases that call quota_summary.
The old TUI history popup path was removed; history now goes through the tool report directly.
These aliases are still OpenCode command templates, so they expand into prompt text before the model/tool chain runs. For the cleanest direct output path, prefer the standalone CLI.
Examples:
quota_summary(period=day) -> todayquota_summary(period=week) -> this weekquota_summary(period=month) -> this monthquota_summary(period=day,last=7) -> last 7 daysquota_summary(period=week,last=8) -> last 8 weeksquota_summary(period=month,last=6) -> last 6 monthsquota_summary(period=month,since=2026-01) -> since Jan 2026{
"command": {
"qday": {
"description": "Today / last N days / since date",
"template": "Run /qday for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=day, toast=true. If `$ARGUMENTS` is a positive integer: period=day, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM-DD: period=day, since=<that date>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM-DD."
},
"qweek": {
"description": "This week / last N weeks / since date",
"template": "Run /qweek for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=week, toast=true. If `$ARGUMENTS` is a positive integer: period=week, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM-DD: period=week, since=<that date>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM-DD."
},
"qmonth": {
"description": "This month / last N months / since month",
"template": "Run /qmonth for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=month, toast=true. If `$ARGUMENTS` is a positive integer: period=month, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM: period=month, since=<that month>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM."
},
"qtoggle": {
"description": "Toggle sidebar usage display on/off",
"template": "Call tool quota_show (no arguments, it toggles)."
}
}
}
The package exposes a standalone CLI dashboard. After installing globally or making the bin available:
npm install -g @leo000001/opencode-quota-sidebar
If you prefer not to install globally, you can also run it with npx @leo000001/opencode-quota-sidebar <args>.
# Current period (single snapshot)
opencode-quota day # today
opencode-quota week # this week (Monday-based)
opencode-quota month # this month
# Multi-period history
opencode-quota day 7 # last 7 days
opencode-quota week 8 # last 8 weeks
opencode-quota month 6 # last 6 months
# Absolute start date
opencode-quota day --since 2026-04-01
opencode-quota week --since 2026-04-01
opencode-quota month --since 2026-01
# Also accepted as positional (equivalent to --since)
opencode-quota day 2026-04-01
opencode-quota month 2026-01
When called without last or --since, the CLI renders a single-period snapshot (QUOTA + TOTALS + PROVIDERS). When called with last or --since, it renders multi-period history with a larger multi-line TREND block.
day = current natural day; week = current natural week (Monday-based); month = current natural monthlast=<N> (number of periods back from now)--since (YYYY-MM-DD for day/week, YYYY-MM for month)--since and --last are mutually exclusivelast is limited to 90 for day, reasonable ranges for week/monthThe TREND block appears only in multi-period mode. Each metric (Sessions, Requests, Tokens, Cached, API Cost) is rendered as a small multi-line bar chart:
*Interpretation example:
Requests 12.3k
04-08 | ███░░░░░░░░░░░░░░░ | 4.1k
04-09 | ██████░░░░░░░░░░░░ | 8.2k
04-10* | █████████████░░░░░ | 12.3k
This means the current bucket has 12.3k requests, and the bar rows below show the relative size of each visible bucket from oldest to newest.
http://localhost:4096 by defaultOPENCODE_BASE_URL to override (e.g. http://192.168.1.10:4096)OPENCODE_BASE_URL is not set, the CLI attempts to start a temporary local server:
opencode serve --hostname=127.0.0.1 --port=<chosen-port>opencode.cmd, then opencode via shell: true, then bash -lc opencode127.0.0.1:4096 and retries on another local port if 4096 is already in useopencode server listening on <url>exit, SIGINT, SIGTERM, uncaught exception monitoring)opencode is in your PATHopencode serve manually for logs or set OPENCODE_BASE_URLshell: true path is usually the most reliable when opencode.cmd is not directly spawnable from Node█░). Requires a UTF-8 capable terminal. Windows users should use Windows Terminal, PowerShell 7+, or a terminal that supports UTF-8. Classic cmd.exe with legacy codepages (CP437/CP850) may render garbled characters.opencode. If none work, ensure opencode or opencode.cmd is on your PATH, or start the server manually and set OPENCODE_BASE_URL.>=18| Variable | Default | Purpose |
|---|---|---|
OPENCODE_BASE_URL | http://localhost:4096 | OpenCode API endpoint; set this if the server is remote or on a non-default port |
OPENCODE_QUOTA_CONFIG_HOME | ~/.config/opencode | Global config directory override |
OPENCODE_QUOTA_DATA_HOME | ~/.local/share/opencode | Global data directory override |
npm install
npm run build
npm test
For local development, load:
file:///ABSOLUTE/PATH/opencode-quota-sidebar/dist/index.js in opencode.jsonfile:///ABSOLUTE/PATH/opencode-quota-sidebar/dist/tui.tsx in tui.jsonOn Windows, use forward slashes in file:/// URLs.
>=18@opencode-ai/plugin / @opencode-ai/sdk ^1.3.5>=1.2.15, TUI config belongs in tui.jsonsession.title value for all clientsREADME.mdREADME.zh-CN.mdCHANGELOG.mdCONTRIBUTING.mdSECURITY.mdFAQs
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
The North Korean malware loader hides in a Packagist-listed package and its GitHub branch to fetch and execute remote code in a likely Contagious Interview-style lure.
Security News
The Rust project is moving toward formal rules on LLM use in contributions after months of internal debate over maintainer burden, code quality, and contributor experience.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.