opencode-provider-status

OpenCode TUI plugin — shows AI provider usage/quota status in the session sidebar using OpenCode's public TUI slots.

• OpenAI / Codex — 5h and weekly subscription quota from auth.json (built-in)
• Anthropic / Claude Code — OAuth availability, plan, rate limit tier, and token expiry from Claude Code credentials (built-in)
• GitHub Copilot — premium interactions remaining from auth.json (built-in)
• Custom HTTP providers — define any endpoint, map JSON fields to display

Auto-refreshes every 60 seconds.

What you get

• Collapsible provider status card in the session sidebar_content slot
• Click the card header to collapse or expand provider details
• Click a provider row to open a details dialog
• Run /provider-status in the TUI command menu to open the status dialog
• Color-coded progress bars (green → yellow → red as usage increases)

Requirements

• OpenCode >= 1.3.13
• Node.js >= 22

Setup

This is a TUI-only plugin. Add it to tui.json only (NOT opencode.json).

Load from npm

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-provider-status"]
}

Local checkout

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["/absolute/path/to/opencode-provider-status/tui.tsx"]
}

Configuration

All options are passed as the second element of the plugin tuple:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    [
      "opencode-provider-status",
      {
        "title": "Provider Status",
        "builtin": ["openai", "anthropic"],
        "custom": [
          {
            "id": "team-gateway",
            "label": "Team Gateway",
            "url": "https://gateway.example.com/key/usage?key=YOUR_KEY",
            "display": "cost",
            "mapping": {
              "spend": "total_spend",
              "budget": "max_budget",
              "detail": "available_models"
            }
          }
        ]
      }
    ]
  ]
}

Top-level options

| Option | Default | Description | |---|---|---| | title | Provider Status | Panel title | | interval_ms | 60000 | Auto-refresh interval (ms) | | timeout_ms | 10000 | API request timeout (ms) | | builtin | ["openai", "anthropic"] | Built-in providers: "openai", "anthropic", "copilot" |

Anthropic support reads the OAuth credentials synchronized by opencode-claude-auth and the local Claude Code credentials file. Anthropic does not expose the same real-time subscription quota endpoint here, so this row shows auth availability, plan/tier metadata, and token expiry rather than remaining message quota.

Custom providers (custom)

Define any HTTP endpoint that returns JSON. The plugin extracts values using dot-notation field paths and renders progress bars.

| Custom field | Description | |---|---| | id | Unique identifier | | label | Display name in the panel | | url | Full API URL (GET or POST) | | method | "GET" (default) or "POST" | | headers | Additional HTTP headers as { "key": "value" } | | body | POST body (if method is POST) | | display | "cost" (dollar spend/budget) or "quota" (percentage used) | | mapping | JSON field → display field mapping |

Mapping fields

For display: "cost":

| Mapping key | Description | Example | |---|---|---| | spend | Path to total spend | "total_spend" | | budget | Path to max budget | "max_budget" | | detail | Path to extra info | "available_models" |

For display: "quota":

| Mapping key | Description | Example | |---|---|---| | used | Path to usage percentage (0-100) | "used_percent" | | detail | Path to extra info | "plan_type" |

Field paths use dot notation: total_spend, available_models.length, etc.

Multiple custom providers

{
  "custom": [
    {
      "id": "team-gateway",
      "label": "Team Gateway",
      "url": "https://gateway.example.com/usage?key=YOUR_KEY",
      "display": "cost",
      "mapping": {
        "spend": "total_spend",
        "budget": "max_budget"
      }
    },
    {
      "id": "custom-quota",
      "label": "Custom Quota",
      "url": "https://api.example.com/quota",
      "display": "quota",
      "headers": { "X-Api-Key": "xxx" },
      "mapping": {
        "used": "data.usage_percent",
        "detail": "data.plan"
      }
    }
  ]
}

Troubleshooting

• Make sure the plugin is only configured in tui.json, not opencode.json
• For a local checkout, use an absolute path to tui.tsx
• After changing config, fully quit and reopen OpenCode
• Check logs in ~/.local/share/opencode/log/ for service=tui.plugin errors

Publishing

Publishing is handled by GitHub Actions when master is updated, or by manual workflow dispatch.

1. Create an npm automation token and add it to the GitHub repository secret NPM_TOKEN.
2. Merge or push changes to master.
3. The workflow automatically bumps the patch version in package.json and package-lock.json, commits it back to master, creates a matching v* tag, and publishes to npm.

The workflow runs npm ci, npm run check, npm version patch --no-git-tag-version, and npm publish --access public.

License

MIT