Small OpenCode plugin for Codex quota visibility.

Instead of checking the web dashboard, you get quota toasts directly in OpenCode.

• Shows Codex quota status as OpenCode toasts.
• Runs a background check on startup and every 10 minutes.
• Keeps noise low: background checks only notify when quota reaches the configured threshold (warn by default, so warn/critical/error).
• Includes JSON output mode for scripts and debugging.

Prerequisite: connect OpenCode to your ChatGPT Plus/Pro plan using OpenCode's native provider setup:

/connect

Choose the OpenAI/ChatGPT plan option, then install this quota plugin.

npm install -g opencode-codex-usage
opencode-codex-usage --install

Then restart OpenCode.

npx opencode-codex-usage --install

Then restart OpenCode.

1. Build:

npm install
npm run build

2. Link and auto-configure OpenCode:

npm link
opencode-codex-usage --install

3. Restart OpenCode.

Manual plugin path (if you prefer editing config directly):

"<repo>"

Add that path to both OpenCode's server plugin config and TUI plugin config.

Version 1.0.0 changes the OpenCode integration from a server-only plugin to paired server and TUI plugins. This is a breaking setup change if you installed an older version manually or have an old plugin path in config.

Old manual plugin paths are obsolete:

"<repo>/dist/index.js"

Use the package root instead:

"<repo>"

Recommended upgrade:

npm install -g opencode-codex-usage@latest
opencode-codex-usage --install

Then restart OpenCode.

The installer updates both OpenCode's server plugin config and TUI plugin config. The /codex-usage command is now registered by the TUI plugin, while background quota checks remain in the server plugin.

The TUI plugin registers a /codex-usage slash command. This means quota checks run locally and the command shows a toast without an assistant turn.

You can still run opencode-codex-usage directly when you want an immediate quota refresh from a shell.

After install verify end-to-end:

OPENCODE_CODEX_QUOTA_TOAST_THRESHOLD=always opencode
/codex-usage

Use /codex-usage or opencode-codex-usage to verify the end-to-end toast flow immediately (no agent invocation).

Flags for opencode-codex-usage:

• -h or --help - show CLI usage and available flags.
• --json or --verbose - print JSON snapshot to stdout on success.
• --pretty - show a human-friendly quota view with ASCII usage bars.
• --no-notify - skip the refresh notification step.
• --retry <count> - retry transient probe failures (0-2). Overrides env for current run.
• --install - update OpenCode server config and TUI config with the plugin path.
• --uninstall - remove the plugin path from OpenCode server config and TUI config.
• --config <path> - with --install/--uninstall, use a non-default OpenCode config path.
• On error, JSON is written to stderr and the process exits non-zero.

Remove global install:

npm uninstall -g opencode-codex-usage

Remove local link:

npm unlink -g opencode-codex-usage

• Background checks run on startup and on interval.
• Background checks trigger a toast only when status meets the configured threshold and gets worse than the previous background state.
• Manual runs can trigger an immediate refresh from any folder.
• Window labels use API-provided window minutes when available (for example 5h window, 7d window), otherwise fallback to window A / window B.

Authentication is handled by OpenCode. Use /connect in OpenCode to connect a ChatGPT Plus/Pro plan before running quota checks.

If the probe reports provided authorization token is expired, run /connect and reconnect your ChatGPT account.

Set polling interval (milliseconds):

OPENCODE_CODEX_QUOTA_POLL_MS=120000

Default is 600000 (10 minutes). Invalid or non-positive values fall back to default.

Set transient retry count for probe failures:

OPENCODE_CODEX_QUOTA_RETRY_COUNT=1

Allowed values: 0, 1 (default), 2. Values above 2 clamp to 2; invalid values fall back to default.

Set probe model (advanced; optional):

OPENCODE_CODEX_QUOTA_MODEL=gpt-5.5

By default, the probe queries the authenticated Codex model list and uses the first supported model returned for the account.

Advanced: override the internal refresh path (optional):

OPENCODE_CODEX_USAGE_SIGNAL_PATH=/tmp/opencode-codex-usage.refresh

Set background toast threshold:

OPENCODE_CODEX_QUOTA_TOAST_THRESHOLD=critical

Allowed values: warn (default), critical, error, always, never.

Set toast duration (milliseconds):

OPENCODE_CODEX_QUOTA_TOAST_DURATION_MS=5000

Default is 5000. Invalid or non-positive values fall back to default.

The probe prints one JSON object (ProbeSnapshot) per run.

Common keys:

• status (for example ok, warn, error)
• statusCode (for example 200, 500, auth, network, timeout)
• used (primary/secondary percent)
• reset (primary/secondary reset duration)
• windowMinutes (primary/secondary window length in minutes, when available)
• plan, profile, probeTokens, error

Error statusCode values:

• auth for auth-path/token issues
• network for transport failures
• timeout for request timeout
• numeric HTTP status codes for server responses

Example:

{
  "status": "warn",
  "statusCode": 200,
  "plan": "plus",
  "profile": "default",
  "used": { "primary": 81, "secondary": 9 },
  "reset": { "primary": "1h0m", "secondary": "7d0h" },
  "windowMinutes": { "primary": 300, "secondary": 10080 },
  "probeTokens": 10
}

npm test
npm run lint
npm run build
npm run format:check

Auto-configure OpenCode with local plugin path:

opencode-codex-usage --install