Codex Status

v0.1.4UI & Themes

opencode-codex-status

OpenCode TUI plugin that shows Codex quota in the sidebar.

Actively maintained

#opencode #opencode-plugin #tui #codex #quota

GitHub repo npm page Homepage

GitHub stars

+2 in 30 days

Monthly installs

204

30 in 7 days

Composite scoreSCORE

42.5

Multi-signal model

Last commit

1 day ago

2026-08-19

Install and configure

opencode.json

Writes to this project's opencode.json — applies to this repository only.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-codex-status@0.1.4"]
}

Writes to ~/.config/opencode/opencode.json — applies to every project.

~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-codex-status@0.1.4"]
}

opencode loads npm dependencies through its embedded runtime on startup and caches them locally — no manual global install needed.

README.md

View original→

An OpenCode TUI plugin that shows your ChatGPT Codex quota in the session sidebar.

It reads your usage from the Codex CLI's own endpoint using credentials that opencode already stores. Checking quota does not consume any of your quota.

Installation

Install the plugin with OpenCode's native installer:

opencode plugin opencode-codex-status --global

Or via npx:

npx opencode-codex-status install

For project-local testing, use OpenCode's project scope:

opencode plugin opencode-codex-status

Or via npx:

npx opencode-codex-status install --project

Restart OpenCode after installing.

Usage

It uses the OpenAI credentials OpenCode already stores. No extra auth setup is needed.

Once loaded, the quota display appears in the TUI sidebar. Run /codex-status to force a refresh, or /codex-status-toggle to show/hide the display on the fly.

Configuration

The installer writes a plugin entry in tui.json. To change options, edit that entry:

{
  "plugin": [["opencode-codex-status", { "pollMs": 60000 }]]
}

Option	Default	Description
`pollMs`	`300000`	Polling interval in milliseconds
`retryCount`	`1`	Retries on transient failure
`authPath`	(auto)	Path to the auth JSON file
`enabled`	`true`	Start with the sidebar display hidden when `false`; toggle at runtime via `/codex-status-toggle`

How it works

The plugin fetches your Codex usage data on startup and periodically every 5 minutes (configurable). It also refreshes after each step completes.

Each quota window shows a label, a progress bar, remaining percent, and estimated time until reset. Error states and stale data are displayed inline.

Project structure

src/
  tui.tsx      – TUI plugin entrypoint and View component
  client.ts    – Auth reading and API fetch
  config.ts    – Plugin option parsing
  format.ts    – Text formatting for bars, times, labels
  manual.ts    – /codex-status command handler
  quota.ts     – Type definitions
  refresh.ts   – Polling and activity-triggered refresh loop
  store.ts     – Solid signal store for quota state
test/
  ...          – Vitest tests covering all modules