opencode-codex-usage-plugin

An OpenCode TUI sidebar plugin that shows Codex 5-hour and weekly quota usage as compact gauges with reset countdowns.

Codex Usage
5h   ███░░░░  week █████▋░
42% · 2h      81% · 7d

This is a maintained fork of zaniluca/opencode-codex-usage-plugin. It keeps the original Codex App/CLI integration and presents the usage data in the gauge style used by the other David Ayers OpenCode plugins.

Features

• Quota gauges — compact eighth-block gauges for the available 5-hour and weekly Codex limits
• Proximity colors — gauge and percentage use the active theme: success <50% → accent 50–74% → warning 75–89% → error ≥90%
• Reset countdowns — short reset times appear beneath each available window
• Compact prompt line — identifies the most constrained window when the sidebar is hidden
• Codex App/CLI support — reads usage through the Codex app-server protocol, sharing a WebSocket-over-Unix server across OpenCode instances
• Live updates — refreshes every 60 seconds and on message/session events
• Silent by design — hidden for non-Codex sessions

Install

opencode plugin --global @davidaayers/opencode-codex-usage-plugin

Or from inside OpenCode: press ctrl+p → "Install Plugin" → @davidaayers/opencode-codex-usage-plugin. Restart OpenCode and the gauges appear once the session uses an OpenAI/Codex model.

From source

OpenCode TUI plugins load from the plugin array in ~/.config/opencode/tui.json (or a project-level tui.json) — not from opencode.jsonc, whose plugin array is server-side only.

// ~/.config/opencode/tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["file:///absolute/path/to/opencode-codex-usage-plugin/dist/tui.js"],
}

Requirements

Install either Codex App or the Codex CLI. The plugin looks for Codex in common locations and on your PATH.

If your Codex command lives somewhere else, set OPENCODE_CODEX_USAGE_COMMAND:

export OPENCODE_CODEX_USAGE_COMMAND="/path/to/codex"

How It Works

• Usage source: the Codex app-server provides normalized 5-hour and weekly rate-limit windows.
• Rendering: the plugin uses OpenTUI and the active OpenCode theme, with the gauge renderer kept separate from the Codex transport.
• Lifecycle: the Effect-based service reuses or starts a shared Codex app-server over a Unix socket, connects with WebSocket, and falls back to a dedicated stdio server when the shared path is unavailable. It owns request timeouts and connection cleanup.

Development

pnpm install
pnpm check
pnpm test
pnpm build

The published plugin entrypoint is dist/tui.js, generated from src/tui.ts.

Roadmap

Cross-repository follow-up work is tracked in the OpenCode Plugins project.

Changelog

See CHANGELOG.md for release history.

Credits

The Codex integration is forked from zaniluca/opencode-codex-usage-plugin. The gauge presentation is inspired by @davidaayers/opencode-go-usage-plugin and @davidaayers/opencode-context-gauge-plugin.

License

MIT. See the upstream project for the original implementation and attribution.