OpenCode plugin that displays your ChatGPT Plus/Pro Codex subscription quota directly in the terminal — no browser needed.
- Single
/codex_quotacommand — a convenient wrapper that asks OpenCode to call the quota tool - Rich Markdown output — themed headers, progress bars, tables rendered by OpenCode TUI
- 5h + Weekly windows — primary 5-hour and secondary weekly usage with local reset clocks
- Code review quota — shown when applicable to your plan
- Credits & spend control — balance, approximate message counts, spending status
- Advisory + warning banners — pacing notes at 50%+, stronger warnings at 80%+, critical at 100%
- Two display modes — full for
/codex_quota, compact for agent/tool usage or/codex_quota compact - Auth from OpenCode — reads your existing
opencode auth logincredentials, no extra setup
Example full-mode output rendered in the OpenCode TUI.
Add to your OpenCode config (~/.config/opencode/config.json or project opencode.json):
{
"plugin": ["opencode-codex-quota"]
}git clone https://github.com/guyinwonder168/opencode-codex-quota.git
cd opencode-codex-quota
npm install
npm run buildThen point OpenCode at your local package directory:
{
"plugin": ["./path/to/opencode-codex-quota"]
}This project is packaged as an npm/path plugin. OpenCode also supports raw local plugin files placed directly in .opencode/plugins/ or ~/.config/opencode/plugins/, but that is a different layout from this repository.
In current OpenCode plugin APIs:
- the
codex_quotatool is exposed to the agent/tool loop - the
/codex_quotaslash command is a wrapper prompt that tells OpenCode to call that tool
That means /codex_quota is convenient and reliable, but it is still LLM-mediated, not a direct no-LLM syscall.
/codex_quota
Shows complete quota details: plan type, primary 5h window, weekly window, code review quota, credits, spend control, and promotional info.
Under the hood, the wrapper prompt asks OpenCode to call the codex_quota tool and present the result.
You can also pass compact to the slash command when you want the shorter table:
/codex_quota compact
Example output:
# OpenAI Codex Subscription
**Plan:** Plus | **Account:** user@example.com
---
## Quota Limits
| Window | Usage | Progress | Resets At |
|--------|-------|----------|------------|
| **Primary (5h)** | 51% | `██████░░░░░░` 51% | 04:06:26 |
| **Weekly** | 40% | `█████░░░░░░░` 40% | 05:46:54 on 9 Apr |
---
> ⚠️ Primary (5h) at 51% — consider pacing your usage.
---
## Code Review Quota
| Window | Usage | Progress | Resets At |
|--------|-------|----------|------------|
| **Weekly** | 0% | `░░░░░░░░░░░░` 0% | 02:37:12 on 11 Apr |
---
## Spend Control
**Status:** ✅ Within limit
---
*Updated: 2026-03-29T12:00:00.000Z*The underlying tool supports mode=compact for concise output when called by an AI agent:
codex_quota(mode="compact")
Example output:
### Codex Quota — Plus
| Window | Usage | Progress | Resets At |
|--------|-------|----------|------------|
| 5h | 51% | `██████░░░░░░` | 04:06:26 |
| Weekly | 40% | `█████░░░░░░░` | 05:46:54 on 9 Apr |
**Status**: ✅ Within limitsSome sections appear only when relevant:
| Section | When Shown |
|---|---|
| Code Review Quota | When your plan includes code review limits |
| Credits | When you have credits or unlimited balance |
| Promotional | When promotional quota is active |
| Warning banners | When any window is 80–99% or 100% |
| Advisory notes | When any window is 50–79% |
- OpenCode installed and configured
- ChatGPT Plus or Pro subscription with Codex access
- OAuth credentials via
opencode auth login(select ChatGPT Plus/Pro)
The plugin shows user-friendly Markdown messages for common issues:
| Error | Message |
|---|---|
| Missing auth | Setup instructions with opencode auth login steps |
| Wrong auth type | OAuth setup instructions |
| Empty token | Re-auth instruction |
| Token expired | Re-auth instruction |
| Network error | Connection check guidance |
| API 401/403 | Token refresh instruction |
| API 429 | Rate limited — wait a few seconds |
| API 5xx | Service unavailable — try later |
| Unexpected response | Partial data with update notice |
opencode-codex-quota/
├── src/
│ ├── index.ts # Plugin entry point, tool definition
│ ├── types.ts # All TypeScript interfaces
│ ├── services/
│ │ ├── auth-reader.ts # Read auth.json → parse JWT → extract credentials
│ │ └── api-client.ts # Call wham/usage → typed QuotaResponse
│ └── formatter/
│ ├── markdown.ts # QuotaResponse → Markdown string
│ └── errors.ts # Error codes → Markdown error messages
└── tests/
├── auth-reader.test.ts
├── api-client.test.ts
├── markdown.test.ts
├── errors.test.ts
├── index.test.ts
└── integration.test.ts
Data flow:
/codex_quota
→ wrapper prompt tells OpenCode to call tool.codex_quota
→ AuthReader: auth.json → JWT → { token, accountId, email }
→ ApiClient: GET wham/usage → QuotaResponse
→ Formatter: QuotaResponse + mode → Markdown string
→ OpenCode TUI renders via Glamour
- Node.js >= 20
- TypeScript >= 6.0
git clone https://github.com/guyinwonder168/opencode-codex-quota.git
cd opencode-codex-quota
npm installnpm run build # TypeScript → dist/
npm run typecheck # Type checking only
npm test # Run all tests
npm run test:coverage # Run tests with coverage
npm run lint # Check code style
npm run lint:fix # Fix code style issuesTests use vitest with the Arrange-Act-Assert pattern. Mocks for fetch and fs are set up per test.
npm test # All tests
npm test -- tests/auth-reader.test.ts # Specific file
npm run test:coverage # With coverage reportContributions are welcome! See CONTRIBUTING.md for guidelines.
MIT © 2026 guyinwonder168
- slkiser/opencode-quota — source of the API endpoint and auth flow discovery
- OpenCode — the AI coding assistant this plugin extends