---
title: Usage Limits
description: Show provider quota windows in the OpenCode sidebar and prompt footer.
sidebar:
  label: Usage Limits
  order: 3
---

## `@mynameistito/opencode-usage-limits`

Usage Limits reads provider quota APIs and authenticated local CLIs, normalizes their different response shapes, and renders the result in OpenCode's TUI. It refreshes every 60 seconds by default, with an effective minimum of 15 seconds.

## Install

```powershell
opencode2 plugin add "@mynameistito/opencode-usage-limits@latest" -g
```

The package contains a TUI entrypoint and a published JSON schema:

- `@mynameistito/opencode-usage-limits/tui`
- `@mynameistito/opencode-usage-limits/schema`

Create `~/.config/opencode/usage-limits.jsonc`. A complete annotated example is available in the repository at [`examples/usage-limits.jsonc`](https://github.com/mynameistito/opencode-plugins/blob/main/packages/opencode-usage-limits/examples/usage-limits.jsonc).

## Minimal configuration

Credentials are discovered from OpenCode auth by default:

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/mynameistito/opencode-plugins/main/packages/opencode-usage-limits/usage-limits.schema.json",
  "providers": {
    "codex": { "enabled": true },
    "zai": { "enabled": true, "authorizationScheme": "raw" },
  },
}
```

The top-level `enabled` flag disables the plugin. Each provider's `enabled` flag controls fetching. `showSidebarBar` and `showFooterBar` control display independently without stopping refreshes.

## Providers

<nav class="provider-logo-grid" aria-label="Usage limit providers">
  <a href="#openai" aria-label="OpenAI">
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="800"
      height="800"
      fill="currentColor"
      viewBox="0 0 24 24"
      aria-hidden="true"
    >
      <path d="M22.282 9.821a6 6 0 0 0-.516-4.91 6.05 6.05 0 0 0-6.51-2.9A6.065 6.065 0 0 0 4.981 4.18a6 6 0 0 0-3.998 2.9 6.05 6.05 0 0 0 .743 7.097 5.98 5.98 0 0 0 .51 4.911 6.05 6.05 0 0 0 6.515 2.9A6 6 0 0 0 13.26 24a6.06 6.06 0 0 0 5.772-4.206 6 6 0 0 0 3.997-2.9 6.06 6.06 0 0 0-.747-7.073M13.26 22.43a4.48 4.48 0 0 1-2.876-1.04l.141-.081 4.779-2.758a.8.8 0 0 0 .392-.681v-6.737l2.02 1.168a.07.07 0 0 1 .038.052v5.583a4.504 4.504 0 0 1-4.494 4.494M3.6 18.304a4.47 4.47 0 0 1-.535-3.014l.142.085 4.783 2.759a.77.77 0 0 0 .78 0l5.843-3.369v2.332a.08.08 0 0 1-.033.062L9.74 19.95a4.5 4.5 0 0 1-6.14-1.646M2.34 7.896a4.5 4.5 0 0 1 2.366-1.973V11.6a.77.77 0 0 0 .388.677l5.815 3.354-2.02 1.168a.08.08 0 0 1-.071 0l-4.83-2.786A4.504 4.504 0 0 1 2.34 7.872zm16.597 3.855-5.833-3.387L15.119 7.2a.08.08 0 0 1 .071 0l4.83 2.791a4.494 4.494 0 0 1-.676 8.105v-5.678a.79.79 0 0 0-.407-.667m2.01-3.023-.141-.085-4.774-2.782a.78.78 0 0 0-.785 0L9.409 9.23V6.897a.07.07 0 0 1 .028-.061l4.83-2.787a4.5 4.5 0 0 1 6.68 4.66zm-12.64 4.135-2.02-1.164a.08.08 0 0 1-.038-.057V6.075a4.5 4.5 0 0 1 7.375-3.453l-.142.08L8.704 5.46a.8.8 0 0 0-.393.681zm1.097-2.365 2.602-1.5 2.607 1.5v2.999l-2.597 1.5-2.607-1.5Z" />
    </svg>
  </a>
  <a href="#zai" aria-label="Z.AI">
    <svg viewBox="0 0 24 24" role="img" aria-hidden="true">
      <path
        fill="currentColor"
        d="M12.606 1.806 10.929 4.194a1.43 1.43 0 0 1-1.161.606H.606V1.794h12ZM24 1.806 9.6 22.206H0l14.4-20.4h9.6ZM11.394 22.206l1.69-2.4a1.43 1.43 0 0 1 1.161-.606h9.149v3.006h-12Z"
      />
    </svg>
  </a>
  <a href="#synthetic" aria-label="Synthetic">
    <svg
      width="10.555555555555555"
      height="10.555555555555555"
      viewBox="0 0 19 19"
      fill="none"
      xmlns="http://www.w3.org/2000/svg"
      role="img"
      aria-hidden="true"
    >
      <path
        d="M8.56067 1.3799L10.4618 1.34671C10.5492 1.34522 10.6286 1.38935 10.6747 1.45923L10.7093 1.53774L11.045 2.92076C11.1559 3.37707 11.4798 3.75232 11.9152 3.92819C12.3419 4.10041 12.8251 4.0605 13.2183 3.82145L14.3036 3.16178C14.3771 3.11703 14.4662 3.1144 14.5407 3.14983L14.6099 3.19745L15.9965 4.57385C16.0577 4.63461 16.0825 4.72126 16.0659 4.80217L16.035 4.88085L15.4788 5.80573C15.2386 6.20505 15.1867 6.68631 15.3299 7.12299L15.4034 7.30728C15.5966 7.71593 15.9524 8.02086 16.3793 8.15073L16.5666 8.19532L17.4238 8.34639C17.5414 8.36729 17.628 8.46852 17.6302 8.58794L17.6642 10.533C17.6662 10.6479 17.5891 10.7499 17.478 10.7794L16.3785 11.0721C15.9508 11.1859 15.5956 11.4767 15.399 11.8666L15.3249 12.0398C15.1648 12.4858 15.2187 12.9804 15.4714 13.3812L16.0028 14.2246C16.0497 14.2991 16.0532 14.3908 16.0168 14.4666L15.9672 14.5358L14.5394 15.9448C14.4825 16.0008 14.4038 16.025 14.3277 16.0139L14.2531 15.9908L13.2136 15.4747C12.8594 15.2989 12.4528 15.2697 12.0801 15.388L11.9219 15.4474C11.5639 15.6067 11.2838 15.8977 11.1361 16.2562L11.0812 16.4134L10.7617 17.5217C10.7312 17.6271 10.6352 17.7006 10.5255 17.7026L8.58735 17.7364C8.46855 17.7385 8.36456 17.6565 8.33878 17.5405L8.08316 16.3817L8.03422 16.2078C7.91462 15.8694 7.67485 15.5859 7.36105 15.4118L7.19756 15.3345L7.04329 15.2815C6.73077 15.1941 6.39776 15.2128 6.0968 15.3342L5.94955 15.4032L4.77293 16.0371C4.6979 16.0774 4.60969 16.0756 4.53755 16.0373L4.47222 15.9877L3.13752 14.5596C3.0776 14.4954 3.05736 14.4064 3.07873 14.3252L3.11353 14.2484L3.7373 13.3331C3.98342 12.9717 4.04895 12.5208 3.923 12.109L3.85746 11.9353L3.78169 11.7911C3.61486 11.5129 3.35814 11.2998 3.05423 11.1865L2.89807 11.1374L1.49728 10.7907C1.38749 10.7635 1.30969 10.6659 1.30755 10.5528L1.27503 8.6898C1.27334 8.58474 1.33722 8.49154 1.43207 8.45363L1.47385 8.44118L2.69615 8.18641C3.14512 8.09283 3.52318 7.80066 3.72943 7.39873L3.80738 7.2196C3.94662 6.83155 3.92084 6.40585 3.73992 6.04091L3.6523 5.8891L3.04806 4.9581C2.98255 4.85725 2.99751 4.72403 3.08453 4.64101L4.58516 3.20932C4.67146 3.12699 4.80459 3.11666 4.90217 3.18523L5.71797 3.75897C6.12951 4.04818 6.65895 4.11193 7.1274 3.92874C7.53749 3.76829 7.85309 3.43752 7.99657 3.02769L8.04812 2.84707L8.32092 1.57747C8.34533 1.46387 8.44449 1.38193 8.56067 1.3799Z"
        fill="white"
        stroke="black"
        stroke-width="1.5"
      />
      <circle
        cx="9.46694"
        cy="9.5416"
        r="2.53895"
        transform="rotate(-1 9.46694 9.5416)"
        fill="white"
        stroke="black"
        stroke-width="1.5"
      />
    </svg>
  </a>
  <a href="#minimax">
    <img src="https://cdn.simpleicons.org/minimax" alt="MiniMax" />
  </a>
  <a href="#qwen">
    <img src="https://cdn.simpleicons.org/qwen" alt="Qwen" />
  </a>
  <a href="#opencode-go" aria-label="OpenCode GO">
    <svg
      class="provider-logo-opencode provider-logo-opencode-dark"
      viewBox="0 0 240 300"
      role="img"
      aria-hidden="true"
    >
      <path d="M0 0h240v300H0z" fill="#F1ECEC" />
      <path d="M60 60h120v180H60z" fill="#4B4646" />
    </svg>
    <svg
      class="provider-logo-opencode provider-logo-opencode-light"
      viewBox="0 0 240 300"
      role="img"
      aria-hidden="true"
    >
      <path d="M0 0h240v300H0z" fill="#211E1E" />
      <path d="M60 60h120v180H60z" fill="#CFCECD" />
    </svg>
  </a>
  <a href="#alibaba-token-plan">
    <img
      src="https://cdn.simpleicons.org/alibabadotcom"
      alt="Alibaba Cloud Bailian"
    />
  </a>
</nav>

### OpenAI

ChatGPT/OpenAI rolling windows, daily, weekly, or monthly. Credentials come from OpenCode `openai` auth, then the Codex auth file. See the [OpenAI documentation](https://developers.openai.com/codex).

### Z.AI

Z.AI Coding Plan token rolling window. Uses OpenCode `zai-coding-plan` or `zai` auth, or `OC_ZAI_API_KEY`. See the [Z.AI Coding Plan documentation](https://docs.z.ai/guides/overview/quick-start).

### Synthetic

Rolling five-hour and weekly quotas. Uses OpenCode `synthetic` auth or `OC_SYNTHETIC_API_KEY`. See the [Synthetic documentation](https://synthetic.new/docs).

### MiniMax

Token Plan rolling five-hour and weekly windows. Uses MiniMax auth or `OC_MINIMAX_TOKEN_PLAN_KEY`. See the [MiniMax documentation](https://www.minimax.io/platform/document).

### Qwen

Aggregate Token Plan credits from the authenticated `qwencloud` CLI. See the [Qwen Code documentation](https://github.com/QwenLM/qwen-code).

### OpenCode GO

Rolling, weekly, and monthly usage from OpenCode GO auth or `OPENCODE_API_KEY`. See the [OpenCode GO documentation](https://opencode.ai/docs/go).

### Alibaba Token Plan

Personal Token Plan five-hour and weekly windows from the authenticated Bailian `bl` CLI (version 1.15.0 or newer). See the [Bailian documentation](https://help.aliyun.com/zh/model-studio/user-guide/obtain-api-key).

## Display and window selection

Sidebar rows show provider labels, usage percentages or counts, reset times, and stale data when a refresh fails. The footer selects the active session's provider and renders a compact primary window.

Supported `sidebarWindow` values are `all`, `rolling`, `daily`, `weekly`, `monthly`, `credits`, and `other`. `footerWindow` accepts `auto` or one of those values. An unavailable explicit choice falls back to the provider's automatic selection, then its first available window.

```jsonc
{
  "refreshIntervalSeconds": 60,
  "showErrors": true,
  "providers": {
    "codex": {
      "enabled": true,
      "label": "Codex",
      "sidebarWindow": "all",
      "footerWindow": "auto",
      "showSidebarBar": true,
      "showFooterBar": true,
    },
  },
}
```

## Alibaba Token Plan

Authenticate the official Bailian CLI once, then enable the adapter:

```sh
bl auth login --console --console-site international
bl usage token-plan --console-region ap-southeast-1 --console-site international --output json
```

```jsonc
{
  "providers": {
    "alibaba-token-plan": {
      "enabled": true,
      "region": "international",
    },
  },
}
```

Use `region: "china"` with the domestic console for mainland China. The plugin does not import browser cookies or store CLI credentials. Missing windows are omitted rather than reported as zero.

## Credential lookup

Most installations need only `enabled: true`. Explicit `apiKey` and `authPath` overrides exist for environments where auto-discovery is not enough. Provider errors are typed internally and intentionally rendered without tokens or response bodies. After a successful refresh, the last good value remains visible when a later request fails.

## Troubleshooting

1. Confirm the plugin is installed with `opencode2 plugin list`.
2. Confirm the provider is enabled in `usage-limits.jsonc`.
3. Confirm the OpenCode auth provider matches the mapping above.
4. For Qwen and Alibaba, confirm the CLI is authenticated and available on the `PATH` inherited by OpenCode.
5. If the package is stale, clear its OpenCode cache and restart OpenCode.

```powershell
Remove-Item -LiteralPath "$HOME\.cache\opencode\packages\@mynameistito\opencode-usage-limits@latest" -Recurse -Force -ErrorAction SilentlyContinue
```