codex-hud
Korean / 한국어
A Claude Code plugin that displays OpenAI Codex usage and rate limits — right inside your Claude Code session.
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: Integrates with claude-hud to show Codex Usage/Weekly rate limits alongside Claude Code's own statusline
- Slash commands: Dedicated commands for usage, costs, and summary
- Dual data sources: Local Codex CLI session logs (no API key needed) + OpenAI Usage API (optional, for dollar costs)
- Zero npm runtime dependencies: Only uses Node.js built-in modules (statusline wrapper requires Bash and Perl)
- Graceful degradation: Works with just local logs if no API key is configured
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%
Usage █░░░░░░░░░ 14% (resets in 4h 37m)
Weekly ██░░░░░░░░ 22% (resets in 5d 18h)
── Codex team ── <- codex-hud
Usage █░░░░░░░░░ 1% (resets in 5h)
Weekly ░░░░░░░░░░ 0% (resets in 7d)
1 session | team
Installation
Option A: via buildwithclaude marketplace
/plugin marketplace add davepoon/buildwithclaude
/plugin install codex-hud@buildwithclaude
Option B: via this repo directly
/plugin marketplace add haenara-shin/codex-hud
/plugin install codex-hud@codex-hud
Option C: 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
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
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: node "${CLAUDE_PLUGIN_ROOT}/dist/index.js" uninstall-statusline
Setup
1. Local logs (automatic)
If you use the Codex CLI or 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:
- Go to platform.openai.com/settings/organization/admin-keys
- Create an Admin key (starts with
sk-admin-...)
- Run
/codex-hud:setup in Claude Code and enter the key
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
Configure and verify your OpenAI Admin API key.
/codex-hud:usage-today / usage-week / usage-month
Show token usage broken down by metrics.
## Codex Usage - Last 7 Days
### Local Sessions (10 sessions)