codex-hud
Korean / 한국어
A Claude Code plugin that displays OpenAI Codex usage and rate limits — right inside your Claude Code session.
Listed in Anthropic's community plugin marketplace and buildwithclaude.
Why?
If you use codex-plugin-cc to delegate tasks to Codex from Claude Code, you have no way to check your Codex rate limits without leaving your terminal. codex-hud fills that gap.
| Existing Tool | What It Does | What It Doesn't Do |
|---|
| claude-hud | Shows Claude Code context, tools, costs | No Codex/OpenAI data |
| codex-plugin-cc | Runs Codex tasks from Claude Code | No usage/rate limit tracking |
| ccusage | CLI tool for local log analysis | Not a Claude Code plugin |
| codex-hud | Codex usage + rate limits inside Claude Code | -- |
Features
- Real-time statusline: shows your active model + reasoning effort, the 5h and Weekly quota as % left (like Codex's own
/status), and context-window usage below claude-hud's statusline — with a 60s refresh so reset countdowns stay current while idle
- Works with both Codex paths: reads rate limits from the rollout logs (interactive TUI) AND from
~/.codex/logs_2.sqlite (the app-server / Claude Code codex plugin path, Codex 0.140+) — all local, no API key, no network
- 4 layouts: expanded / horizontal / inline / compact, configurable with live previews
- Slash commands: setup, configure, usage, costs, summary, and more
- Plan-agnostic: renders on any Codex plan (free, Plus, Pro, Team, Enterprise) — unreported rate-limit windows are skipped, never crash the statusline
- Zero npm runtime dependencies: Node.js built-ins only (statusline wrapper uses Bash; the app-server source needs Node ≥ 22.5 or the
sqlite3 CLI)
- Optional dollar costs: OpenAI Admin API key enables the
costs-* commands; everything else works without it
Statusline Integration
When paired with claude-hud, codex-hud adds Codex rate limits below the Claude Code statusline:
[Opus 4.6 (1M context)] <- claude-hud
my-project
Context ██░░░░░░░░ 19%
── Codex gpt-5.5·xhigh ── <- codex-hud
5h Usage ██████████ 99% left (resets 19:38 · 3h 55m)
Weekly ███████░░░ 71% left (resets 15:04 on 22 Jun · 5d 23h)
Context ██░░░░░░░░ 18% (47k/258k)
team
The header shows the model and reasoning effort of your most recent Codex turn. The 5h and Weekly rows show how much quota is left (bars fill as remaining, matching Codex's /status), with both the absolute reset time and the time remaining; the Context bar tracks context-window occupancy (shown as used). When Codex reports a reached rate limit, a red ⚠ LIMIT alert appears in the header. The reset format (absolute / relative / both) and which elements show are configurable via /codex-hud:configure.
Installation
Option A: via Anthropic's community marketplace (recommended)
Anthropic-maintained directory, nightly-synced from the internal review pipeline.
/plugin marketplace add anthropics/claude-plugins-community
/plugin install codex-hud@claude-community
Option B: via buildwithclaude marketplace
/plugin marketplace add davepoon/buildwithclaude
/plugin install codex-hud@buildwithclaude
Option C: via this repo directly
/plugin marketplace add haenara-shin/codex-hud
/plugin install codex-hud@codex-hud
Option D: from source
git clone https://github.com/haenara-shin/codex-hud.git
cd codex-hud
npm install && npm run build
Then in Claude Code:
/plugin marketplace add /path/to/codex-hud
/plugin install codex-hud@codex-hud
Statusline setup
After installing the plugin, run:
/codex-hud:setup
