codex-hud — Claude Code plugin: what it does, how to install
codex-hud displays OpenAI Codex quotas, rate limits, and context usage directly in your Claude Code statusline without leaving the terminal.
MIT ★ 8 updated 2026-06-24
/plugin marketplace add anthropics/claude-plugins-community
/plugin install codex-hud@claude-communityWhat codex-hud does
codex-hud tracks your active model, context window usage, and remaining capacity for both 5-hour and weekly Codex quotas. When paired with claude-hud, it renders these metrics directly in the terminal statusline, updating reset countdowns every 60 seconds while idle.
Rate limit tracking works offline. The plugin parses rollout logs, reads ~/.codex/logs_2.sqlite, or queries the codex app-server RPC depending on the installed Codex version. It does not require runtime npm packages or an API key for basic usage.
Parsing logs on Codex 0.140–0.141 requires Node.js 22.5 or higher, or the system sqlite3 CLI. For Codex 0.142 and newer, the codex executable must exist in your PATH.
What it helps with
- check 5-hour and weekly Codex rate limits without leaving the session
- monitor context window consumption directly in the statusline
- inspect token usage breakdowns for the current day or week
- track dollar expenses using an optional OpenAI Admin key
Example prompts for the agent
- Configure the statusline integration:
/codex-hud:setup - Display token metrics for today:
/codex-hud:usage-today - Change statusline layout and display options:
/codex-hud:configure
How to install codex-hud
Plugin marketplace
/plugin marketplace add anthropics/claude-plugins-community/plugin install codex-hud@claude-communityStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about codex-hud
How do I install codex-hud in Claude Code?
First run /plugin marketplace add anthropics/claude-plugins-community inside Claude Code. Then install the package by running /plugin install codex-hud@claude-community.
Does codex-hud require an OpenAI API key?
Basic rate limit and token tracking operates offline using local files and RPC without an API key. You only need an OpenAI Admin API key if you want to track costs in dollars.
What are the runtime requirements?
Codex 0.140–0.141 requires Node.js 22.5 or newer, or the sqlite3 CLI installed. Codex 0.142 or later needs the codex command available in your system PATH.
Source text
SKILL.md · MIT
# codex-hud
[](https://github.com/haenara-shin/codex-hud/stargazers)
[](https://github.com/haenara-shin/codex-hud/network/members)
[](https://github.com/haenara-shin/codex-hud/watchers)
[](https://github.com/haenara-shin/codex-hud/blob/main/LICENSE)
**[Korean / 한국어](README_KR.md)**
A [Claude Code](https://claude.ai/code) plugin that displays OpenAI Codex usage and rate limits — right inside your Claude Code session.
> Listed in [Anthropic's community plugin marketplace](https://github.com/anthropics/claude-plugins-community) and [buildwithclaude](https://github.com/davepoon/buildwithclaude).
## Why?
If you use [codex-plugin-cc](https://github.com/openai/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](https://github.com/jarrodwatts/claude-hud) | Shows Claude Code context, tools, costs | No Codex/OpenAI data |
| [codex-plugin-cc](https://github.com/openai/codex-plugin-cc) | Runs Codex tasks from Claude Code | No usage/rate limit tracking |
| [ccusage](https://github.com/ryoppippi/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](https://github.com/jarrodwatts/claude-hud)'s statusline — with a 60s refresh so reset countdowns stay current while idle
- **Works across every Codex path & version**: reads rate limits from the rollout logs (interactive TUI), `~/.codex/logs_2.sqlite` (app-server, Codex 0.140–0.141), and the `codex app-server` RPC (Codex 0.142+, which writes nothing to disk) — newest-wins, 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 0.140–0.141 DB source needs Node ≥ 22.5 or the `sqlite3` CLI; the 0.142+ source needs the `codex` CLI on PATH)
- **Optional dollar costs**: OpenAI Admin API key enables the `costs-*` commands; everything else works without it
## Statusline Integration
When paired with [claude-hud](https://github.com/jarrodwatts/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
```bash
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
```
This command is idempotent and only touches the statusline integration:
- Creates the symlink at `~/.claude/codex-hud-statusline.sh`
- Updates `~/.claude/settings.json` so the Codex rate limits appear below claude-hud's statusline (sets `statusLine.refreshInterval` to 60s to keep reset countdowns fresh while idle)
Restart Claude Code or run `/reload-plugins` to see the Codex statusline.
To enable dollar cost tracking (optional, requires OpenAI Admin API key):
```
/codex-hud:setup-key
```
To remove the statusline integration, run `/codex-hud:uninstall` (restores your previous statusline if one was saved).
## Setup
### 1. Local logs (automatic)
If you use the [Codex CLI](https://github.com/openai/codex) or [codex-plugin-cc](https://github.com/openai/codex-plugin-cc), session logs at `~/.codex/sessions/` are parsed automatically. No configuration needed.
### 2. OpenAI Usage API (optional, for dollar costs)
To see dollar costs, you need an **OpenAI Admin API key**:
1. Go to [platform.openai.com/settings/organization/admin-keys](https://platform.openai.com/settings/organization/admin-keys)
2. Create an Admin key (starts with `sk-admin-...`) and copy it to your clipboard
3. Run `/codex-hud:setup-key` in Claude Code — the key is read from the clipboard, never typed into the chat
Or set the `OPENAI_ADMIN_KEY` environment variable.
> **Note**: If you're on a Teams/Enterprise subscription, dollar costs may not be relevant since usage is included in your plan. The local log-based rate limit tracking works without any API key.
## Commands
### `/codex-hud:setup`
Install the statusline integration (idempotent — safe to re-run).
### `/codex-hud:setup-key`
Configure and verify your OpenAI Admin API key (clipboard-based; only needed for dollar costs).
### `/codex-hud:configure`
Guided flow for display options: layout, presets, language, bar width.
### `/codex-hud:uninstall`
Remove the statusline integration and restore your previous statusline.
### `/codex-hud:usage-today` / `usage-week` / `usage-month`
Show token usage broken down by metrics.
```
## Codex Usage - Last 7 Days
### Local Sessions (10 sessions)
| Metric | Tokens |
|--------------|----------|
| Input | 3.4M |
| Cached Input | 2.7M |
| Output | 114.9k |
| Reasoning | 82.4k |
| **Total** | **3.5M** |
Rate limit: 94% left (5h) / 86% left (7d) | Plan: team
```
### `/codex-hud:costs-today` / `costs-week` / `costs-month` *(beta)*
Show cost breakdown by billing line item (requires Admin API key).
> **Beta**: This feature has not been tested with a live Admin API key. If you're on a pay-per-token plan and encounter incorrect data, please [open an issue](https://github.com/haenara-shin/codex-hud/issues).
### `/codex-hud:summary`
Quick one-line summary of today's Codex activity.
```
Codex today: $1.23 | 1.8M tokens (1.4M cached) | 3 sessions | Rate: 99%/100% left
```
## Data Sources
| Source | Data | Auth Required |
|--------|------|---------------|
| Rollout logs (`~/.codex/sessions/`) | Token usage, rate limits, session count, model (interactive Codex TUI) | None |
| App-server DB (`~/.codex/logs_2.sqlite`) | Rate limits + model for Codex **0.140–0.141** via the app-server / codex plugin | None (Node ≥ 22.5 or `sqlite3` CLI) |
| Codex app-server RPC (`codex app-server`) | Rate limits for Codex **0.142+** (which writes none to disk); cached 5 min, refreshed in the background; model/effort from `~/.codex/config.toml` | None (Codex CLI on PATH) |
| OpenAI Usage API (`/v1/organization/costs`) | Dollar costs by billing line item | Admin API key |
| OpenAI Usage API (`/v1/organization/usage/completions`) | Org-wide token usage by model | Admin API key |
## Updating
To update to a newer version, **run both commands** (the plugin manager UI's "Update now" button alone does not refresh the marketplace cache):
```
/plugin marketplace update codex-hud
/plugin update codex-hud@codex-hud
/reload-plugins
```
Substitute `codex-hud` with your marketplace alias — `claude-community` for Anthropic's community marketplace, `buildwithclaude` for buildwithclaude, or `codex-hud` for the direct repo install.
## Requirements
- Node.js >= 18.0.0. For app-server rate limits: Codex **0.142+** reads them via the `codex` CLI on PATH; Codex **0.140–0.141** needs **Node >= 22.5 (or the `sqlite3` CLI)** to read `~/.codex/logs_2.sqlite`. Older Node still works for rollout-based usage.
- [Claude Code](https://claude.ai/code)
- [Codex CLI](https://github.com/openai/codex) or [codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- [claude-hud](https://github.com/jarrodwatts/claude-hud) (optional, for statusline integration)
- OpenAI Admin API key (optional, for cost data)
## Acknowledgments
codex-hud was inspired by [claude-hud](https://github.com/jarrodwatts/claude-hud) — which solved the same usage-visibility problem for Claude Code itself. codex-hud extends that idea to OpenAI Codex and integrates with claude-hud via the included wrapper script when both are installed.
## Changelog
### v0.10.0
- **Codex 0.142+ support.** Codex 0.142 stopped writing rate limits to disk entirely (it fetches them live and hands them to clients over the app-server). codex-hud now reads them by calling `codex app-server` JSON-RPC `account/rateLimits/read` itself, caching the result (5-min TTL) and refreshing in a detached background process so the statusline stays fast. Fixes the disappearing 5h / Weekly bars on 0.142.
- Maps the new camelCase fields (`usedPercent` / `windowDurationMins` / `resetsAt` / `rateLimitReachedType`); model + effort fall back to `~/.codex/config.toml` since the RPC doesn't return them.
- Source priority is newest-wins across rollout logs, `logs_2.sqlite` (0.140–0.141), and the app-server RPC (0.142+), so it works across Codex versions.
### v0.9.0
- **Works with the app-server / Codex plugin path.** Codex 0.140+ run via the app-server (e.g. the Claude Code codex plugin) doesn't write rate limits to the rollout logs — it logs them to `~/.codex/logs_2.sqlite`. codex-hud now reads the newest snapshot from there (local, no network/auth), merged with rollout data by freshness. This fixes "No Codex sessions found" for users who only use Codex through the plugin.
- **Reasoning effort** in the model badge (e.g. `gpt-5.5·xhigh`), read from `~/.codex/config.toml`.
- **`5h Usage` label** for the primary window (derived from its duration), matching Codex's own `/status`.
- **Quota shown as "% left"** with bars that fill as remaining — e.g. `5h Usage ██████████ 99% left (resets 19:38 · 3h 58m)` — matching Codex `/status`. (The Context bar still shows used%.)
- Requires Node >= 22.5 or the `sqlite3` CLI for the new app-server source; degrades gracefully otherwise.
### v0.8.0
- **Absolute reset times** (like Codex's own `/status`). Reset hints now show the clock time a window resets — `resets 19:38`, or `resets 15:04 on 22 Jun` once it's past today — alongside the time remaining: `(resets 19:38 · 4h 37m)`. New `resetStyle` option (`both` (default) / `absolute` / `relative`), localized for ko (`리셋 19:38 · 4h 37m`). Configurable via `/codex-hud:configure` with live previews.
### v0.7.0
- **Live previews in `/codex-hud:configure`.** When choosing a layout, each option now shows a side-by-side preview of how your statusline will actually look — rendered by the real statusline code (sample data, with your current toggles applied), so the preview can never drift from the result. Adds a `preview` CLI subcommand (`node dist/index.js preview --set layout=compact`) that emits plain, color-free output for the question UI.
### v0.6.2
- **Horizontal layout restored** to its classic shape (header + side-by-side bars + footer). The v0.6.1 one-liner lives on as a separate **`inline`** layout — pick whichever you prefer via `/codex-hud:configure` (4 layouts now: expanded / horizontal / inline / compact).
### v0.6.1
- **Horizontal layout redesigned as a true one-liner** (claude-hud style): `Codex team gpt-5.5·medium │ Usage ████░░░░░░ 42% (2h) │ Weekly ████████░░ 81% (2d 7h) │ Context ██░░░░░░░░ 18% │ 2s`. Previously it still used separate header/footer lines; now everything — bars included — sits on one line, matching the look of claude-hud's metric row above it.
### v0.6.0
- **Model + effort badge**: the header now shows which model and reasoning effort your most recent Codex turn used (e.g. `── Codex gpt-5.5·medium ──`). Toggle with `showModel`.
- **Context bar**: context-window occupancy of the most recent session (`Context ██░░░░░░░░ 18% (47k/258k)`), mirroring claude-hud's context display for the Codex side. Toggle with `showContext`.
- **`⚠ LIMIT` alert**: when Codex reports `rate_limit_reached_type`, a red badge appears in the header — catching the case where requests are blocked while the percentage bars are still below 100%.
- All three render in every layout (expanded / horizontal / compact) and come from the same tail-read window — no extra I/O.
### v0.5.2
- Compact layout session-count suffix is now localized (`15s` / `15 세션`).
- `costs --daily` date column labeled `(UTC)` to match API bucket boundaries.
- Install output only claims the previous statusline was saved when it actually was.
- Investigated narrowing command `allowed-tools` beyond `Bash(node:*)`: `${CLAUDE_PLUGIN_ROOT}` substitution is documented for skill content/hooks/MCP configs but not frontmatter, so the narrowing is deferred rather than risk silently breaking command auto-approval.
### v0.5.1
Quality release driven by a full multi-dimension code review (33 findings, adversarially verified).
- **Fix (install):** the statusline entry point is now a small launcher script that resolves the current plugin install at runtime. Previously a symlink pointed into the version-numbered plugin cache, so the first `/plugin update` silently blanked the entire statusline.
- **Security (key handling):** `/codex-hud:setup-key` now reads the Admin key from the clipboard and pipes it via stdin (`setup --key-stdin`). The key no longer appears in chat transcripts or process arguments.
- **Fix (accuracy):** the freshest rate-limit snapshot is now chosen by event timestamp (was: file-path order, which could freeze the bars on a stale snapshot for hours); sessions spanning midnight are picked up for "today".
- **Perf:** large rollout files (>256KB) are tail-read instead of fully parsed on every render — a 20MB active session drops from ~200ms to ~1ms per render.
- **Robustness:** install now preserves unrelated `statusLine` fields and saves your previous statusline; `/codex-hud:uninstall` (new command) restores it. settings.json writes are atomic. The wrapper survives missing `node` on PATH with a visible message, and finds claude-hud through plugin metadata regardless of marketplace alias.
- **Fix (costs):** pagination guard against non-advancing API cursors; a visible warning when the API truncates results.
- Docs: corrected stale `/codex-hud:setup` → `/codex-hud:setup-key` references everywhere, completed CLI help, configure flow contradictions resolved.
### v0.5.0
- **Fix:** statusline no longer crashes on plans where a rate-limit window is absent (e.g. free / no-limit plans report `primary` or `secondary` as `null`). Missing windows are skipped and the rest still render.
- **Fix:** `costs-month` / `usage-month` now report the full range. The OpenAI Costs/Usage APIs cap daily buckets per page (default 7), so 30-day queries previously returned only ~7 days with no error. The plugin now sizes the request and follows `has_more`/`next_page` pagination.
- **Add:** statusline registration sets `refreshInterval: 60` so reset countdowns stay current while the session is idle.
- **Chore:** drop the explicit `commands[]` array from `plugin.json` (commands are auto-discovered), add `$schema` to both manifests, and verify against current Claude Code 2.1.x / Codex CLI 0.125+ contracts.
### v0.4.0
- Add horizontal layout (Usage + Weekly side-by-side); 3 layouts total (expanded / horizontal / compact).
## License
MIT
© haenara-shin · MIT · haenara-shin/codex-hud