← Back to README

Configuration

Most people only need the examples on this page. The full option list is at the bottom.

Where settings live

OpenCode Quota normally keeps its settings in one separate file:

• Project install: <your-repo>/opencode-quota/quota-toast.jsonc
• Global install: usually ~/.config/opencode/opencode-quota/quota-toast.jsonc
• Custom config directory: $OPENCODE_CONFIG_DIR/opencode-quota/quota-toast.jsonc

Strict .json files also work. Run /quota_status if you are unsure which file is active.

opencode.jsonc loads the main plugin. tui.jsonc loads TUI features. Put the settings below in quota-toast.jsonc, not tui.jsonc.

Common changes

The installer chooses allWindows by default. If the setting is absent, the built-in default is singleWindow.

Example

{
  // Find providers from OpenCode configuration and authentication.
  "enabledProviders": "auto",

  // Show every quota reset period as percentage remaining.
  "formatStyle": "allWindows",
  "percentDisplayMode": "remaining",
  // Optional linear estimate for supported fixed windows. Off when omitted.
  "quotaProjection": "runway",
  "percentLabelStyle": "bare",
  // Use dense compound reset countdowns instead of the spaced default.
  "resetTimeSpaced": false,
  "accountingDetail": "summary",

  // Keep TUI slash-command results with normal messages.
  "tuiCommandDisplay": "inline",

  // Show the sidebar and prefer OpenCode Go's Five-hour row while collapsed.
  "tuiSidebarPanel": {
    "enabled": true,
    "opencodeGoPreferredWindow": "rolling",
  },
  "enableToast": false,
  "resetNotifications": { "enabled": false, "windows": ["weekly"] },
  "tuiCompactStatus": { "enabled": false },
  // Show a quota progress bar under the prompt.
  "tuiPromptBar": { "enabled": true },
}

Restart OpenCode after changing the file.

Show accounting detail

accountingDetail is a root setting with two values:

• "summary" (default) keeps primary accounting rows and shows at most one supporting basis expression per percentage row.
• "detailed" also admits supplementary rows and, on wide output, can show separate Used, Limit, and Remaining facts.

It applies to human output from /quota, terminal show, popup toasts, the TUI sidebar, Compact status, and the prompt bar below the input. Narrow, tiny, 36-column sidebar, and compact layouts can omit basis or supplementary detail rather than truncate a financial value. The prompt bar always keeps one primary row and omits supplementary rows and basis details.

This setting is independent of formatStyle, which selects quota windows, and percentDisplayMode, which selects used or remaining percentage direction. Those display settings do not change provider input or cache identity. Changing only accountingDetail reprojects an available snapshot immediately; later collection still follows normal cache expiry, disabled-cache, and refresh rules. The words Used, Limit, and Remaining always keep their literal meanings in either percentage mode.

Estimate when fixed quota runs out

quotaProjection: "runway" is optional and off by default. It adds a Runs out estimate to eligible percentage rows on shared Web/Desktop and TUI /quota, terminal show, popup toasts, the expanded Sidebar, Compact status, and the prompt bar.

{
  "quotaProjection": "runway",
}

The estimate is a straight-line average since the confirmed fixed window began: used percentage divided by elapsed time, then remaining percentage divided by that average rate. It is not a recent-rate forecast, trend, alert, budget, or prediction model. Changing percentDisplayMode between remaining and used does not change the calculation.

The provider's exact reset countdown stays separate from the estimate. If the calculated exhaustion is before reset, full displays use Runs out ≈ 1h 50m; Compact status and the prompt bar use r/o ≈ 1h 50m, where r/o means “runs out.” The approximation marker always has one following space, duration units are spaced, and partial minutes round up. If current use would last through the reset, displays say lasts past reset.

Availability is deliberately narrow. A row needs a finite percentage, its original observation time, a nonzero elapsed interval, and explicit fixed-window start, end/reset, and full-reset evidence. OpenAI's known API rate-limit windows, xAI periods with explicit currentPeriod.start and currentPeriod.end, Cursor cycles with cursorBillingCycleStartDay, Qwen's maintained UTC-day window, and configured local-estimate utc-day windows can qualify. Rolling windows, RPM rows, balance/status/unlimited rows, Cursor's calendar-month fallback, and windows inferred only from labels do not. Unsupported rows are simply unchanged.

This option changes human presentation only. It reuses cached provider snapshots without another provider request, preserves the provider observation time, and does not add fields to JSON export v2.

Notify when quota becomes available again

Reset notifications are opt-in. They reuse provider snapshots already collected by OpenCode Quota, so enabling them does not add provider requests.

{
  "resetNotifications": {
    "enabled": true,
    "windows": ["weekly"],
  },
}

The first observation establishes a baseline. A success toast appears only after OpenCode Quota observes the advertised reset boundary, a newer reset timestamp, and an increase in remaining quota. A local acknowledgment prevents the same reset from being announced again after restart. The state file stores pseudonymous SHA-256 identity keys plus remaining percentages and reset, observation, and acknowledgment timestamps. Literal account source identifiers, display labels, and credentials are not written to it.

Reset notifications use the server popup-toast surface. They do not appear in slash-command or CLI output, Sidebar, Compact status, status collection, telemetry, or JSON exports, and require a host that supports tui.showToast. Supported window names are fiveHour, hourly, daily, weekly, monthly, and yearly.

Include subagent session tokens

Session totals use only the current session by default. To include the current session and every descendant or subagent session once:

{
  "showSessionTokens": true,
  "sessionTokenScope": "tree",
}

This scope applies to the embedded session-token output in /quota on Web and TUI, popup toasts, the TUI sidebar, and the compact line below the message input. It does not change /tokens_session or /tokens_session_all; those commands keep their explicit current-session and session-tree meanings.

Custom providers

A custom provider connects OpenCode Quota to a provider that is not built in, or lets you tune a maintained local estimate.

Use the guided command:

npx @slkiser/opencode-quota@latest provider add

It asks what kind of provider you have, previews the complete canonical merged global config, and asks before writing. It never asks for a response body, credential, or secret value. For json-v1, it guides you through the optional rows path and each mapping one field at a time. The same schema validator used at startup checks the constructed adapter before the preview.

The command updates the active global quota config. If a global quota-toast.jsonc or .json exists, it uses that file. Otherwise it uses the global opencode.jsonc or .json. Project custom-provider definitions are not allowed.

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "quotaToast": {
      "enabledProviders": "auto",
      "quotaProviders": [
        {
          "id": "openrouter-primary",
          "providerId": "openrouter",
          "label": "OpenRouter Primary",
          "mode": "remote-api",
          "url": "https://openrouter.ai/api/v1/key",
          "format": "openrouter-key-v1",
          "apiKeyEnv": "OPENROUTER_API_KEY",
        },
        {
          "id": "private-gateway",
          "label": "Private Gateway Estimate",
          "mode": "local-estimate",
          "modelIds": ["model-a"],
          "windows": [
            {
              "id": "daily",
              "label": "Daily",
              "type": "utc-day",
              "requestLimit": 1000,
              "usdBudget": 25,
            },
          ],
        },
      ],
    },
  },
  "provider": {
    "private-gateway": {
      "models": {
        "model-a": {},
      },
    },
  },
}

See Providers for response formats and setup details.

More recipes

{
  "enabledProviders": ["copilot", "openai", "google-agy"],
}

{
  "percentDisplayMode": "used",
}

{
  "tuiCompactStatus": {
    "enabled": true,
    "homeBottom": true,
    "sessionPrompt": false,
  },
}

{
  "resetTimeDecimals": 1,
}

{
  "resetTimeSpaced": false,
  "percentLabelStyle": "bare",
}

{
  "maintainerAnnouncements": {
    "enabled": true,
    "home": true,
  },
}

{
  "requestTimeoutMs": 12000,
}

{
  "export": {
    "enabled": true,
  },
}

npx @slkiser/opencode-quota init --sync-legacy-config

Full configuration reference

Most settings go in the same opencode-quota/quota-toast.jsonc or .json sidecar described above. The guided editor maintains quotaProviders in that authoritative sidecar when one exists; otherwise it uses the global OpenCode experimental.quotaToast section; do not duplicate it in a second file.

Existing experimental.quotaToast settings remain supported. Quota settings do not live in tui.json.