{
  "markdown": "# codex-hud\n\n[![GitHub stars](https://img.shields.io/github/stars/haenara-shin/codex-hud?style=social)](https://github.com/haenara-shin/codex-hud/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/haenara-shin/codex-hud?style=social)](https://github.com/haenara-shin/codex-hud/network/members)\n[![GitHub watchers](https://img.shields.io/github/watchers/haenara-shin/codex-hud?style=social)](https://github.com/haenara-shin/codex-hud/watchers)\n[![GitHub license](https://img.shields.io/github/license/haenara-shin/codex-hud)](https://github.com/haenara-shin/codex-hud/blob/main/LICENSE)\n\n**[Korean / 한국어](README_KR.md)**\n\nA [Claude Code](https://claude.ai/code) plugin that displays OpenAI Codex usage and rate limits — right inside your Claude Code session.\n\n> Listed in [Anthropic's community plugin marketplace](https://github.com/anthropics/claude-plugins-community) and [buildwithclaude](https://github.com/davepoon/buildwithclaude).\n\n## Why?\n\nIf 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.\n\n| Existing Tool | What It Does | What It Doesn't Do |\n|---|---|---|\n| [claude-hud](https://github.com/jarrodwatts/claude-hud) | Shows Claude Code context, tools, costs | No Codex/OpenAI data |\n| [codex-plugin-cc](https://github.com/openai/codex-plugin-cc) | Runs Codex tasks from Claude Code | No usage/rate limit tracking |\n| [ccusage](https://github.com/ryoppippi/ccusage) | CLI tool for local log analysis | Not a Claude Code plugin |\n| **codex-hud** | **Codex usage + rate limits inside Claude Code** | -- |\n\n## Features\n\n- **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\n- **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\n- **4 layouts**: expanded / horizontal / inline / compact, configurable with live previews\n- **Slash commands**: setup, configure, usage, costs, summary, and more\n- **Plan-agnostic**: renders on any Codex plan (free, Plus, Pro, Team, Enterprise) — unreported rate-limit windows are skipped, never crash the statusline\n- **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)\n- **Optional dollar costs**: OpenAI Admin API key enables the `costs-*` commands; everything else works without it\n\n## Statusline Integration\n\nWhen paired with [claude-hud](https://github.com/jarrodwatts/claude-hud), codex-hud adds Codex rate limits below the Claude Code statusline:\n\n```\n[Opus 4.6 (1M context)]                                  <- claude-hud\nmy-project\nContext ██░░░░░░░░ 19%\n── Codex gpt-5.5·xhigh ──                                 <- codex-hud\n5h Usage ██████████ 99% left (resets 19:38 · 3h 55m)\nWeekly   ███████░░░ 71% left (resets 15:04 on 22 Jun · 5d 23h)\nContext  ██░░░░░░░░ 18% (47k/258k)\nteam\n```\n\nThe 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`.\n\n## Installation\n\n### Option A: via Anthropic's community marketplace *(recommended)*\n\nAnthropic-maintained directory, nightly-synced from the internal review pipeline.\n\n```\n/plugin marketplace add anthropics/claude-plugins-community\n/plugin install codex-hud@claude-community\n```\n\n### Option B: via buildwithclaude marketplace\n\n```\n/plugin marketplace add davepoon/buildwithclaude\n/plugin install codex-hud@buildwithclaude\n```\n\n### Option C: via this repo directly\n\n```\n/plugin marketplace add haenara-shin/codex-hud\n/plugin install codex-hud@codex-hud\n```\n\n### Option D: from source\n\n```bash\ngit clone https://github.com/haenara-shin/codex-hud.git\ncd codex-hud\nnpm install && npm run build\n```\n\nThen in Claude Code:\n\n```\n/plugin marketplace add /path/to/codex-hud\n/plugin install codex-hud@codex-hud\n```\n\n### Statusline setup\n\nAfter installing the plugin, run:\n\n```\n/codex-hud:setup\n```\n\nThis command is idempotent and only touches the statusline integration:\n- Creates the symlink at `~/.claude/codex-hud-statusline.sh`\n- 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)\n\nRestart Claude Code or run `/reload-plugins` to see the Codex statusline.\n\nTo enable dollar cost tracking (optional, requires OpenAI Admin API key):\n\n```\n/codex-hud:setup-key\n```\n\nTo remove the statusline integration, run `/codex-hud:uninstall` (restores your previous statusline if one was saved).\n\n## Setup\n\n### 1. Local logs (automatic)\n\nIf 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.\n\n### 2. OpenAI Usage API (optional, for dollar costs)\n\nTo see dollar costs, you need an **OpenAI Admin API key**:\n\n1. Go to [platform.openai.com/settings/organization/admin-keys](https://platform.openai.com/settings/organization/admin-keys)\n2. Create an Admin key (starts with `sk-admin-...`) and copy it to your clipboard\n3. Run `/codex-hud:setup-key` in Claude Code — the key is read from the clipboard, never typed into the chat\n\nOr set the `OPENAI_ADMIN_KEY` environment variable.\n\n> **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.\n\n## Commands\n\n### `/codex-hud:setup`\n\nInstall the statusline integration (idempotent — safe to re-run).\n\n### `/codex-hud:setup-key`\n\nConfigure and verify your OpenAI Admin API key (clipboard-based; only needed for dollar costs).\n\n### `/codex-hud:configure`\n\nGuided flow for display options: layout, presets, language, bar width.\n\n### `/codex-hud:uninstall`\n\nRemove the statusline integration and restore your previous statusline.\n\n### `/codex-hud:usage-today` / `usage-week` / `usage-month`\n\nShow token usage broken down by metrics.\n\n```\n## Codex Usage - Last 7 Days\n\n### Local Sessions (10 sessions)\n\n| Metric       | Tokens   |\n|--------------|----------|\n| Input        | 3.4M     |\n| Cached Input | 2.7M     |\n| Output       | 114.9k   |\n| Reasoning    | 82.4k    |\n| **Total**    | **3.5M** |\n\nRate limit: 94% left (5h) / 86% left (7d) | Plan: team\n```\n\n### `/codex-hud:costs-today` / `costs-week` / `costs-month` *(beta)*\n\nShow cost breakdown by billing line item (requires Admin API key).\n\n> **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).\n\n### `/codex-hud:summary`\n\nQuick one-line summary of today's Codex activity.\n\n```\nCodex today: $1.23 | 1.8M tokens (1.4M cached) | 3 sessions | Rate: 99%/100% left\n```\n\n## Data Sources\n\n| Source | Data | Auth Required |\n|--------|------|---------------|\n| Rollout logs (`~/.codex/sessions/`) | Token usage, rate limits, session count, model (interactive Codex TUI) | None |\n| 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) |\n| 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) |\n| OpenAI Usage API (`/v1/organization/costs`) | Dollar costs by billing line item | Admin API key |\n| OpenAI Usage API (`/v1/organization/usage/completions`) | Org-wide token usage by model | Admin API key |\n\n## Updating\n\nTo update to a newer version, **run both commands** (the plugin manager UI's \"Update now\" button alone does not refresh the marketplace cache):\n\n```\n/plugin marketplace update codex-hud\n/plugin update codex-hud@codex-hud\n/reload-plugins\n```\n\nSubstitute `codex-hud` with your marketplace alias — `claude-community` for Anthropic's community marketplace, `buildwithclaude` for buildwithclaude, or `codex-hud` for the direct repo install.\n\n## Requirements\n\n- 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.\n- [Claude Code](https://claude.ai/code)\n- [Codex CLI](https://github.com/openai/codex) or [codex-plugin-cc](https://github.com/openai/codex-plugin-cc)\n- [claude-hud](https://github.com/jarrodwatts/claude-hud) (optional, for statusline integration)\n- OpenAI Admin API key (optional, for cost data)\n\n## Acknowledgments\n\ncodex-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.\n\n## Changelog\n\n### v0.10.0\n\n- **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.\n- Maps the new camelCase fields (`usedPercent` / `windowDurationMins` / `resetsAt` / `rateLimitReachedType`); model + effort fall back to `~/.codex/config.toml` since the RPC doesn't return them.\n- 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.\n\n### v0.9.0\n\n- **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.\n- **Reasoning effort** in the model badge (e.g. `gpt-5.5·xhigh`), read from `~/.codex/config.toml`.\n- **`5h Usage` label** for the primary window (derived from its duration), matching Codex's own `/status`.\n- **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%.)\n- Requires Node >= 22.5 or the `sqlite3` CLI for the new app-server source; degrades gracefully otherwise.\n\n### v0.8.0\n\n- **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.\n\n### v0.7.0\n\n- **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.\n\n### v0.6.2\n\n- **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).\n\n### v0.6.1\n\n- **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.\n\n### v0.6.0\n\n- **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`.\n- **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`.\n- **`⚠ 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%.\n- All three render in every layout (expanded / horizontal / compact) and come from the same tail-read window — no extra I/O.\n\n### v0.5.2\n\n- Compact layout session-count suffix is now localized (`15s` / `15 세션`).\n- `costs --daily` date column labeled `(UTC)` to match API bucket boundaries.\n- Install output only claims the previous statusline was saved when it actually was.\n- 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.\n\n### v0.5.1\n\nQuality release driven by a full multi-dimension code review (33 findings, adversarially verified).\n\n- **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.\n- **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.\n- **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\".\n- **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.\n- **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.\n- **Fix (costs):** pagination guard against non-advancing API cursors; a visible warning when the API truncates results.\n- Docs: corrected stale `/codex-hud:setup` → `/codex-hud:setup-key` references everywhere, completed CLI help, configure flow contradictions resolved.\n\n### v0.5.0\n\n- **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.\n- **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.\n- **Add:** statusline registration sets `refreshInterval: 60` so reset countdowns stay current while the session is idle.\n- **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.\n\n### v0.4.0\n\n- Add horizontal layout (Usage + Weekly side-by-side); 3 layouts total (expanded / horizontal / compact).\n\n## License\n\nMIT\n",
  "bytes": 16962,
  "sha": "5fda95b8b48675b714251a7efcb4ef99f5fe8235486a833f256c6f8bd7f2c140",
  "repo_slug": "haenara-shin/codex-hud",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_haenara_shin_codex_hud_codex_hud_b1d8bc61/readme"
}