oc-usage-limits-plugin - GitLite

KO | EN

gitlite — search

#tailwindcss #privacy #awesome-list #kotlin #react #dotnet #windows #agents #awesome #cloud-native

oc-usage-limits-plugin

(★ 9)

OpenCode TUI plugin for usage limits of AI Providers

File Explorer

ZIP Download

- config.json
- README.md
- - bug_report.yml
  - config.yml
  - feature_request.yml
- - ci.yml
  - codeql.yml
  - release.yml
- dependabot.yml
- pull_request_template.md
- - codex.test.ts
  - helpers.ts
  - index.test.ts
  - minimax.test.ts
  - opencode-go.test.ts
  - qwen.test.ts
  - runtime.test.ts
  - synthetic.test.ts
  - zai-coding-plan.test.ts
- components.test.ts
- components.test.tsx
- config.test.ts
- coordinator.test.ts
- errors.test.ts
- format.test.ts
- plugin.test.tsx
- session.test.ts
- usage.test.ts
- utils.test.ts
- usage-limits.jsonc
- 00-opencode-v2-migration-overview.md
- 01-v2-api-and-source-migration.md
- 02-release-and-changesets-lanes.md
- 03-parallel-worktree-execution.md
- 04-validation-and-open-questions.md
- changeset-add.ts
- test-package.ts
- - command.ts
  - config-decode.ts
  - config-read.ts
  - missing-credentials.ts
  - rate-limit.ts
  - response-decode.ts
  - timeout.ts
  - transport.ts
- - codex.ts
  - definition.ts
  - index.ts
  - minimax.ts
  - opencode-go.ts
  - qwen.ts
  - synthetic.ts
  - zai-coding-plan.ts
- - url.ts
- components.tsx
- config-schema.ts
- config.ts
- coordinator.ts
- errors-shared.ts
- errors.ts
- format.ts
- index.ts
- plugin.tsx
- providers.ts
- session.ts
- types.ts
- usage.ts
- utils.ts
.gitignore
AGENTS.md
bun.lock
bunfig.toml
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
knip.json
lefthook.yml
LICENSE
oxfmt.config.ts
oxlint.config.ts
package.json
README.md
SECURITY.md
tsconfig.json
tsdown.config.ts
usage-limits.schema.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

OpenCode TUI plugin that shows Codex, OpenCode GO, ZAI, Synthetic, MiniMax Token Plan, and Qwen usage limits in the sidebar and prompt footer.

> [!IMPORTANT]
> Not really active development as I am using OpenCode2 now, relevant code can be found here https://github.com/mynameistito/opencode-plugins/tree/main/packages/opencode-usage-limits

## Features

- Adds a `Usage Limits` block under the sidebar `Context` section.
- Shows current Codex usage windows from OpenAI/Codex auth.
- Shows current ZAI quota windows from ZAI Coding Plan auth.
- Shows current Synthetic rolling 5-hour and weekly windows.
- Shows current MiniMax Token Plan rolling 5-hour and weekly windows.
- Shows current Qwen Token Plan windows from the local `qwencloud` CLI.
- Shows current OpenCode GO rolling, weekly, and monthly windows.
- Adds compact prompt-footer usage when the current session uses an OpenAI, OpenCode GO, ZAI Coding Plan, Synthetic, or MiniMax Token Plan model.
- Providers are toggled from `~/.config/opencode/usage-limits.jsonc`.
- Reads OpenCode-connected credentials first, then falls back to explicit config/env credentials.

## Install

Standard OpenCode uses the stable package from npm's `latest` dist-tag. Install it globally with:

```bash
opencode plugin oc-usage-limits-plugin -g
```

- `-g` / `--global` installs to `~/.config/opencode/tui.json`.
- Without `-g`, installs locally to `<project>/.opencode/tui.json` (requires a git worktree).
- `--force` replaces an existing pinned version.

The CLI installs the `latest` package and updates the TUI plugin config for you. The package entrypoint is `oc-usage-limits-plugin/tui`.

OpenCode v2 development has moved to [`opencode-plugins/packages/opencode-usage-limits`](https://github.com/mynameistito/opencode-plugins/tree/main/packages/opencode-usage-limits).

To configure it manually instead, add the plugin to `~/.config/opencode/tui.json`:

```jsonc
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["oc-usage-limits-plugin"],
}
```

OpenCode TUI plugins are configured in `tui.json`, not `opencode.jsonc`.

Restart OpenCode after changing TUI plugin config.

### Troubleshooting

#### Reinstall or refresh the cached plugin

If the plugin is stale, broken, or needs a clean reinstall, quit OpenCode and remove its cache. OpenCode caches immutable package versions, so clearing the cache is required when a `tui.json` entry still resolves to an older version.

PowerShell:

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

macOS/Linux:

```bash
rm -rf ~/.cache/opencode/packages/oc-usage-limits-plugin@latest
```

Start OpenCode again and it will reinstall the plugin from the existing `tui.json` entry. If the plugin is no longer configured, run the install command again:

```bash
opencode plugin oc-usage-limits-plugin -g
```

- **Dependency conflicts involving `@opencode-ai/plugin`** usually mean OpenCode's package cache contains an older plugin API package. Update OpenCode, clear the cached plugin as above, then retry the install. This package does not publish OpenCode runtime packages as peer dependencies.
- **`No versions available`** right after a release means a supply-chain cooldown policy (e.g. `min-release-age`) is blocking the fresh version. Wait for the cooldown window to pass, or install a previously vetted version instead.

## Usage Config

Create `~/.config/opencode/usage-limits.jsonc`. The same file lives at [`examples/usage-limits.jsonc`](examples/usage-limits.jsonc) and can be copied verbatim:

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/mynameistito/oc-usage-limits-plugin/main/usage-limits.schema.json",
  "enabled": true,
  "refreshIntervalSeconds": 60,
  "requestTimeoutMs": 10000,
  "showErrors": true,
  "providers": {
    "codex": {
      "enabled": true,
      "label": "Codex",
      "showSidebarBar": true,
      "showFooterBar": true,
      "sidebarWindow": "all",
      "footerWindow": "auto",
    },
    "zai": {
      "enabled": true,
      "label": "ZAI",
      "apiKey": "{env:OC_ZAI_API_KEY}", // Optional fallback when OpenCode auth has no ZAI key
      "authorizationScheme": "raw",
    },
    "synthetic": {
      "enabled": true,
      "label": "Synthetic",
      "apiKey": "{env:OC_SYNTHETIC_API_KEY}", // Optional fallback when OpenCode auth has no Synthetic key
    },
    "minimax": {
      "enabled": true,
      "label": "MiniMax",
      "apiKey": "{env:OC_MINIMAX_TOKEN_PLAN_KEY}", // Optional fallback when OpenCode auth has no MiniMax key
    },
  },
}
```

### Minimal config

If you only need Codex and ZAI with auto-discovered credentials:

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

Disabled providers are hidden:

```jsonc
"providers": {
  "codex": { "enabled": true },
  "zai": { "enabled": false }
}
```

`enabled` is the plugin master switch, while each provider's `enabled` field controls fetching. Provider `showSidebarBar` and `showFooterBar` independently control that provider's displays without stopping refreshes. `sidebarWindow` filters that provider's sidebar windows (`all`, `rolling`, `daily`, `weekly`, `monthly`, `credits`, or `other`), and `footerWindow` selects its footer window (`auto` or one of those kinds). Both display flags default to `true`; `sidebarWindow` defaults to `all` and `footerWindow` to `auto`.

## Providers

| Provider ID | Service | Env var | Auth header | Default base URL |
| --- | --- | --- | --- | --- |
| `codex` | ChatGPT Codex usage | — | Bearer | `https://chatgpt.com/backend-api` |
| `zai` | Z.AI Coding Plan quota | `OC_ZAI_API_KEY` | raw / Bearer | `https://api.z.ai` |
| `synthetic` | Synthetic quotas | `OC_SYNTHETIC_API_KEY` | Bearer | `https://api.synthetic.new` |
| `minimax` | MiniMax Token Plan | `OC_MINIMAX_TOKEN_PLAN_KEY` | Bearer | `https://www.minimax.io` |
| `qwen` | Qwen Token Plan | `qwencloud` CLI | CLI | — |
| `opencode-go` | OpenCode GO usage | `OPENCODE_API_KEY` | Bearer | `https://opencode.ai/zen/go/v1` |

Synthetic always uses `Bearer` auth and ignores `authorizationScheme`.

Set `baseUrl` on `minimax` to `https://api.minimaxi.com` when using the mainland-China region. MiniMax always uses `Bearer` auth and ignores `authorizationScheme`.

## Credential Lookup

`authPath` and `apiKey` are optional overrides. Typical OpenCode users only need `enabled: true`; `label` is an optional display override. Credentials are discovered automatically from OpenCode auth and provider defaults. Set `apiKey` (or `authPath` to a standalone key file) only when auto-discovery is not enough.

Codex lookup order:

1. OpenCode auth at `~/.local/share/opencode/auth.json`, provider `openai`.
2. Codex auth file from `authPath`, default `~/.codex/auth.json`.

ZAI lookup order:

1. Config `authPath`, which can point at OpenCode auth JSON or a simple `{ "key": "..." }` / `{ "apiKey": "..." }` JSON file.
2. OpenCode auth at `~/.local/share/opencode/auth.json`, provider `zai-coding-plan`.
3. OpenCode auth provider `zai`.
4. Config `apiKey`, including `{env:OC_ZAI_API_KEY}` references.

Synthetic lookup order:

1. Config `authPath` JSON file (`{ "key": "..." }` / `{ "apiKey": "..." }` / `{ "synthetic": { "key": "..." } }`).
2. OpenCode auth at `~/.local/share/opencode/auth.json`, provider `synthetic`.
3. Config `apiKey`, including `{env:OC_SYNTHETIC_API_KEY}` references.

MiniMax Token Plan lookup order:

1. Config `authPath` JSON file (`{ "key": "..." }` / `{ "apiKey": "..." }` / `{ "minimax-coding-plan": { "key": "..." } }`).
2. OpenCode auth at `~/.local/share/opencode/auth.json`, provider `minimax-coding-plan`, `minimax`, or `minimax-token-plan`.
3. Config `apiKey`, including `{env:OC_MINIMAX_TOKEN_PLAN_KEY}` references.

## Display

Sidebar rows look like:

```txt
Usage Limits
codex
  5h: 42% used resets 1h 2m
  weekly: 12% used resets 3d 4h
ZAI
  tokens: 18% used resets 2h
  MCP: 6% used
Synthetic
  5h: 0% used resets 11m
  weekly: 11% used resets 7m
MiniMax
  5h: 10% used resets 2h 56m
```

Prompt footer shows compact usage when the current session model belongs to a supported provider:

```txt
5h: 42% used resets 1h 2m
```

Provider mapping:

- OpenCode provider `openai` -> Codex usage.
- OpenCode provider `zai-coding-plan` -> ZAI token usage.
- OpenCode provider `synthetic` -> Synthetic usage.
- OpenCode provider `minimax-coding-plan` -> MiniMax Token Plan usage (prompt footer); `minimax` is also accepted as an alias.
- OpenCode provider `qwen` -> Qwen Token Plan usage.
- OpenCode provider `opencode-go` -> OpenCode GO usage.

## Development

```bash
bun install
bun run typecheck
bun run test
bun run check
bun run build
```

The package exposes a TUI entrypoint at `oc-usage-limits-plugin/tui` for OpenCode's package plugin loader.

## Notes

- The refresh interval defaults to 60 seconds.
- The effective minimum refresh interval is 15 seconds.
- Provider work starts in a scoped coordinator after both TUI slots are registered. Disposal interrupts the coordinator and its active provider work.
- Errors are intentionally short and do not include auth tokens or response bodies.
- MiniMax Token Plan returns `{ model_remains, base_resp }`; the per-model `current_interval_status` and `current_weekly_status` are treated as `1` = in plan and `3` = not in plan, and a window is hidden when its status is `3` (the API otherwise reports a meaningless `100%` remaining for a non-existent bucket).