OpenCode Usage Plugin

Track AI provider rate limits and quotas in real-time.

Features

- Live rate limits – See Codex/OpenAI hourly/weekly limits at a glance
- Anthropic subscription limits – Track Claude OAuth windows (5h, 7d, Sonnet/Opus/cowork tiers)
- Proxy quota stats – Monitor Mirrowel Proxy credentials and tier usage
- Copilot usage – Track GitHub Copilot chat + completions quotas
- Z.ai usage – Track GLM Coding Plan 5-hour token quota and monthly tool quota
- OpenRouter usage – Track API credit usage and remaining balance
- Inline status – Results appear directly in your chat, no context switching
- Zero setup – Auto-detects providers from your existing config

Installation

Add to your opencode.json:

``json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@howaboua/opencode-usage-plugin"]
}
`

OpenCode installs dependencies automatically on next launch.

Configuration

The plugin creates a default config file on first run at:

Linux/macOS: ~/.config/opencode/usage-config.jsonc
Windows: %APPDATA%\opencode\usage-config.jsonc

`jsonc
{
// REQUIRED: Proxy server endpoint (default: "http://localhost:8000")
// Leave empty ONLY if you don't use the proxy
"endpoint": "http://localhost:8000",

// REQUIRED: API key for proxy auth (default: "VerysecretKey")
// Leave empty if your proxy doesn't require authentication
"apiKey": "VerysecretKey",

// Optional: Request timeout in milliseconds (default: 10000)
"timeout": 10000,

// Optional: Z.ai API endpoint (default: "https://api.z.ai")
"zaiEndpoint": "https://api.z.ai",

// Optional: Show/hide providers in /usage output
"providers": {
"openai": true,
"anthropic": true,
"proxy": true,
"copilot": true,
"zai": true,
"openrouter": true
},

// Model group display configuration (optional)
"modelGroups": {
// Show all model groups from proxy (default: true)
// When true: auto-discovers all groups, uses displayNames as overrides
// When false: only shows groups listed in displayNames (whitelist mode)
"showAll": true,

// Override display names for specific groups (optional)
// Groups not listed here use their original name from the proxy
"displayNames": {
"g3-pro": "Gemini Pro",
"g3-flash": "Gemini Flash",
"claude": "Claude"
}
}
}
`

> ⚠️ Important: If using the Mirrowel Proxy, both endpoint and apiKey must be set. The proxy defaults to endpoint: http://localhost:8000 and apiKey: VerysecretKey. If you changed these during your proxy setup, you MUST update your config file to match.

$3

The modelGroups section controls how quota groups are displayed:

| showAll | displayNames | Behavior |
|-----------|----------------|----------|
| true (default) | empty/missing | Show all groups with original names |
| true | provided | Show all groups, apply display name overrides |
| false | provided | Only show groups in displayNames (whitelist mode) |
| false | empty/missing | Shows no groups (all filtered out) |
| missing section | — | Legacy behavior (hardcoded group whitelist) |

If missing, the plugin creates a default template on first run.

$3

Copilot is detected from either of these locations:

- ~/.local/share/opencode/copilot-usage-token.json
- ~/.local/share/opencode/auth.json with a github-copilot entry
- ~/.config/opencode/copilot-quota-token.json (optional override)

Usage

$3

`
/usage
`

$3

`
/usage codex
/usage anthropic
/usage claude
/usage proxy
/usage copilot
/usage zai
/usage glm
/usage openrouter
/usage or
`

$3

`
/usage support
`

Supported Providers

| Provider | Source |
|----------|--------|
| Codex / OpenAI | Auth tokens + /wham/usage endpoint |
| Anthropic Claude | OAuth profile + /api/oauth/usage windows |
| Mirrowel Proxy | Local /v1/quota-stats endpoint |
| GitHub Copilot | GitHub internal usage APIs |
| Z.ai GLM Coding Plan | chat.z.ai auth + Z.ai usage APIs |
| OpenRouter | API key + openrouter.ai/api/v1/key |

Troubleshooting

Proxy shows "not configured" error
- Ensure endpoint and apiKey are set in usage-config.jsonc
- Default values: endpoint: http://localhost:8000, apiKey: VerysecretKey
- If you changed these during proxy setup, update your config file to match
- Verify your proxy is running at the specified endpoint

Missing provider data
- Use providers: { ... } in config to disable unused providers
- For Codex: Ensure you have valid auth tokens
- For Copilot: Check token file locations in Configuration section above
- For Z.ai: Ensure your OpenCode auth includes chat.z.ai credentials
- For Anthropic: Ensure Claude OAuth credentials are available (anthropic in auth.json)
- For OpenRouter: Ensure OpenRouter API key is available (openrouter or or in auth.json)

Config file not found
- The plugin auto-creates usage-config.jsonc on first run
- Check the path in Configuration section above
- Manually create the file if needed

See AGENTS.md` for internal architecture.