claude-hud

Real-time heads-up display for Claude Code and Codex

Context health · Tool activity · Agent tracking · Rate limits · Git status

---

---

What You See

[Opus 4.6] ████████░░ 78% | main* | 2 CLAUDE.md | 5 MCPs | 4 hooks | ⏱️ 23m | ◐ thinking
◐ Edit: .../auth.ts | ✓ Read ×4 | ✓ Grep ×3 | ✓ Bash ×2
◐ Explore [haiku]: Finding auth patterns (1m 32s)
▸ Fix authentication token refresh (2/5)

5h current ●●○○○○○○○○  21% ⟳ 3:00pm
7d weekly  ●●●●●○○○○○  52% ⟳ mar 12, 8:00pm
7d sonnet  ○○○○○○○○○○   0% ⟳ mar 12, 8:00pm
extra      ○○○○○○○○○○ $0.00/$50.00

Line	What	Why
Session	Model, context %, git branch, configs, thinking mode	Know when to compact before it's too late
Tools	Running + completed tools with targets	Watch Claude work in real-time
Agents	Subagent type, model, description, elapsed	See what's happening in parallel
Todos	Current task + progress counter	Track completion live
Rate limits	5-hour, 7-day, extra usage with reset times	Never get surprised by throttling

Install

git clone https://github.com/barkleesanders/claude-hud
cd claude-hud
npm ci && npm run build

For Claude Code, add to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node /path/to/claude-hud/dist/index.js"
  }
}

Replace /path/to/claude-hud with the actual path.

For Codex, launch it through the tmux wrapper because Codex does not expose Claude Code's native statusLine hook. The wrapper starts Codex in the main tmux pane and keeps this HUD in a 10-line pane directly underneath:

npm run build
npm run codex:tmux

To show only the HUD pane for an already-running Codex session:

npm run codex:hud

To render the latest Codex session once:

node dist/index.js --codex

Features

Context Health

Visual meter with color coding as your context fills up.

Threshold	Color	Action
<70%	Green	Normal
70-85%	Yellow	Warning
>85%	Red	Shows token breakdown
>95%	Red	Shows ⚠️ COMPACT

Git Integration

Shows current branch and dirty status directly in the status line.

main*     ← dirty (uncommitted changes)
feature   ← clean

Thinking Mode

Indicates whether extended thinking is enabled.

◐ thinking    ← enabled (magenta)
◑ thinking    ← disabled (dimmed)

Rate Limits

Fetches your Anthropic API usage via OAuth and displays:

• Current — 5-hour rolling window with reset time
• Weekly — 7-day all-models window with reset time
• Opus 7d — Opus-specific weekly window (when present)
• Sonnet 7d — Sonnet-specific weekly window (when present)
• Extra — Overage credits used vs monthly limit

Color-coded progress bars: green at low usage, through orange and yellow, to red above 90%.

Cached for 5 minutes. Uses claude-code/* User-Agent to avoid 429 rate-limit errors during active sessions (learned from CodexBar). Token resolved from macOS Keychain, ~/.claude/.credentials.json, or CLAUDE_CODE_OAUTH_TOKEN env var.

For Codex sessions, the HUD reads the rate-limit events Codex writes to ~/.codex/sessions:

• 5h current — Codex primary; the prefix comes from Codex window_minutes when reported.
• 7d weekly — Codex secondary; the prefix comes from Codex window_minutes when reported.
• credits — Codex overage/credit state when Codex reports it (none, enabled, unlimited, or the reported balance).

The Codex watch pane redraws only when the rendered HUD changes, so it avoids the full-pane clear that causes visible flicker.

Tool Activity

Tracks tools from the session transcript:

◐ Edit: .../auth.ts | ✓ Read ×4 | ✓ Grep ×3

• Running tools show a spinner + target file
• Completed tools aggregate by type with counts

Agent Tracking

Shows subagent type, model, description, and elapsed time:

◐ Explore [haiku]: Finding auth patterns (1m 32s)
✓ code-reviewer: Review authentication changes (45s)

Todo Progress

▸ Fix authentication token refresh (2/5)
✓ All todos complete (5/5)

Architecture

Claude Code → stdin JSON → claude-hud → stdout → terminal
Codex       → ~/.codex/sessions JSONL → claude-hud → tmux pane
           ↘ transcript/session JSONL → tools, agents, todos
           ↘ OAuth/Codex rate-limit events → rate limits
           ↘ git CLI → branch, dirty status
           ↘ settings/config files → thinking mode, configs

Data Sources

Data	Source	Accuracy
Model, tokens, context	stdin JSON from Claude Code	Native (exact)
Tools, agents, todos	Transcript JSONL parsing	Real-time
Rate limits	Anthropic OAuth usage API	Cached 60s
Git info	git CLI	Real-time
Config counts	File system scan	Real-time

File Structure

src/
├── index.ts              Entry point
├── stdin.ts              Parse Claude's JSON input
├── transcript.ts         Parse transcript JSONL
├── config-reader.ts      Read MCP/rules/hooks configs
├── rate-limits.ts        OAuth token + API rate limits
├── git-info.ts           Git branch + dirty status
├── types.ts              TypeScript interfaces
└── render/
    ├── index.ts           Render coordinator
    ├── session-line.ts    Model, context, git, thinking
    ├── tools-line.ts      Tool activity
    ├── agents-line.ts     Agent status
    ├── todos-line.ts      Todo progress
    ├── rate-limits-line.ts Rate limit bars
    └── colors.ts          ANSI color helpers

Development

git clone https://github.com/barkleesanders/claude-hud
cd claude-hud
npm ci
npm run build
npm test

Test manually

echo '{"model":{"display_name":"Opus 4.6"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000},"cwd":"/your/project"}' | node dist/index.js

Re-record demo video

# Requires: npm i -g webreel
webreel record demo
ffmpeg -y -i assets/demo.mp4 -vf "fps=15,scale=900:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=128:stats_mode=diff[p];[s1][p]paletteuse=dither=bayer:bayer_scale=3" -loop 0 assets/demo.gif

Requirements

• Claude Code v1.0.80+
• Node.js 18+
• jq, curl, git (for rate limits and git info)

Credits

• Originally built by Jarrod Watts — session, tools, agents, and todos lines
• Rate limits, git integration, and thinking mode by Barklee Sanders, inspired by kamranahmedse/claude-statusline
• Logo generated with nano-banana
• Demo video recorded with WebReel

License

MIT — see LICENSE