Stop Flying Blind in Claude Code: Claude HUD Exposes Everything

You're twenty minutes into a complex refactoring session. Claude Code is churning through files, spinning up subagents, and you have absolutely no idea what's happening behind that polite blinking cursor. Is your context window about to explode? Did that agent you spawned five minutes ago finish its task or crash silently? Are you burning through your rate limits like there's no tomorrow?

This is the invisible nightmare every Claude Code power user knows too well.

Anthropic's CLI tool is brilliant, but it's deliberately minimal. That minimalism becomes a liability when you're managing multi-file edits, delegating tasks to autonomous agents, or pushing the boundaries of context-heavy conversations. You need a heads-up display. You need Claude HUD — the open-source plugin that's turning Claude Code from a black box into a glass cockpit.

Built by Jarrod Watts and already gaining serious traction in the developer community, Claude HUD is the real-time status layer you didn't know you were missing. And once you install it, you'll never code without it again.

What is Claude HUD?

Claude HUD is a native plugin for Claude Code that transforms your terminal into an information-rich command center. Unlike external monitoring tools that require separate windows or tmux panes, Claude HUD leverages Claude Code's built-in statusline API to render live session metrics directly below your input prompt — no window management, no context switching, zero friction.

The project emerged from a genuine pain point: Claude Code's default interface tells you almost nothing about internal state. You type, Claude responds, and the machinery in between remains opaque. Jarrod Watts, a developer deeply embedded in the AI tooling ecosystem, recognized that power users needed transparency without sacrificing the terminal's streamlined aesthetic.

What makes Claude HUD genuinely exciting isn't just the data it surfaces — it's the architectural elegance. The plugin receives native JSON payloads from Claude Code via stdin, parses transcript activity for tool/agent/todo states, and outputs formatted statuslines that Claude Code renders automatically. No hacks, no unsupported APIs, no brittle screen scraping. This is officially-supported extensibility working exactly as intended.

The repository has seen rapid adoption because it solves problems that compound at scale. Solo developers managing complex codebases, teams running parallel agent workflows, and consultants tracking billable context usage all find immediate value. With support for custom color schemes, multiple layout modes, Chinese localization, and granular configuration options, Claude HUD scales from casual enhancement to mission-critical infrastructure.

Key Features That Make Claude HUD Essential

Native Context Window Monitoring

The crown jewel. Claude HUD displays your actual context usage — not estimates, not guesses, but real token counts reported by Claude Code itself. Watch the visual bar shift from green to yellow to red as you approach limits. The plugin automatically scales with Claude Code's reported context window size, including newer 1M-context sessions. This alone prevents the catastrophic "context exceeded" failures that kill long-running sessions.

Real-Time Tool Activity Tracking

See exactly what Claude is doing: ◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2. No more wondering if that file search completed or if the edit operation is still pending. Tool activity lines appear dynamically when there's action to show, keeping your display clean while ensuring visibility when it matters.

Live Agent Orchestration Visibility

Running subagents? Claude HUD tracks them: ◐ explore [haiku]: Finding auth code (2m 15s). You see which model each agent uses, its current objective, and elapsed runtime. This transforms agent delegation from "fire and forget" anxiety into confident orchestration.

Todo Progress Integration

When Claude creates task lists, you get instant progress tracking: ▸ Fix authentication bug (2/5). Milestone visibility keeps complex multi-step operations mentally manageable.

Subscriber Rate Limit Intelligence

For paid Claude users, HUD displays authentic rate limit consumption with configurable visual formatting. See your 5-hour and 7-day usage windows, reset countdowns, and warning thresholds — all synchronized with Anthropic's official data.

Git Context Integration

Project path, branch name, dirty state, ahead/behind indicators, even file change statistics. Claude HUD makes your terminal statusline as informative as a modern IDE's status bar, configurable from 1-3 directory levels deep.

Performance-Optimized Updates

Refresh cycles every ~300ms ensure responsiveness without terminal flicker or CPU thrashing. The plugin's efficient JSON parsing and output buffering maintain smooth interaction even during intensive sessions.

Use Cases Where Claude HUD Transforms Your Workflow

Long-Running Refactoring Sessions

You're modernizing a 50k-line codebase across twelve files. Hours in, context creep is inevitable — but with Claude HUD's real-time percentage and token display, you get early warning before truncation destroys your session state. The visual bar turns yellow at your configured threshold, giving you time to consolidate, summarize, or checkpoint.

Multi-Agent Research Operations

You dispatch three subagents: one to explore the API surface, one to audit security patterns, one to draft documentation. Without HUD, you're switching contexts blindly, wondering if agents completed or diverged. With HUD, all three appear in your statusline with live status — you orchestrate confidently, intervening precisely when needed.

Rate-Conscious Consulting Work

Your client has strict budget controls. Claude HUD's usage tracking lets you monitor consumption in real-time, pace your requests strategically, and provide accurate session accounting. The configurable time-format options (relative countdown, absolute reset time, or both) let you optimize around rate limit windows.

Complex Todo-Driven Development

Claude breaks down your "implement OAuth2" request into twelve subtasks. HUD's todo progress line (▸ Implement token refresh (7/12)) maintains your mental map without scrolling through transcript history. You always know completion state at a glance.

Cross-Platform Team Environments

With Linux tmpfs workarounds, Windows Node.js runtime guidance, and macOS restart procedures documented, Claude HUD deploys consistently across your heterogeneous team. The Chinese localization option (中文) supports international collaborators without forcing English labels.

Step-by-Step Installation & Setup Guide

Getting Claude HUD running takes under two minutes. Follow these exact steps:

Step 1: Add the Plugin Marketplace

Inside any Claude Code session, register the plugin source:

/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the Plugin

Linux users — critical prerequisite:

On Linux systems where /tmp is a separate tmpfs filesystem, installation fails with EXDEV: cross-device link not permitted. Fix this by setting a custom temporary directory before launching Claude Code:

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

Then execute the install in that session:

/plugin install claude-hud

This is a known Claude Code platform limitation, not a HUD bug.

Step 3: Reload Plugins

/reload-plugins

Step 4: Configure the Statusline

/claude-hud:setup

Windows users — runtime requirement:

If setup reports no JavaScript runtime found, install Node.js LTS:

winget install OpenJS.NodeJS.LTS

Restart your shell, then rerun /claude-hud:setup.

Step 5: Restart Claude Code

The new statusLine configuration requires a full restart to activate. On Windows specifically, ensure a complete restart — not just session reconnect — after setup writes the config.

Verification: After restart, you should see the HUD appear below your input prompt. If missing, confirm setup completed and restart again fully.

REAL Code Examples from the Repository

Let's examine actual implementation patterns from the Claude HUD codebase and documentation.

Example 1: Basic HUD Display Structure

The default two-line display provides essential information density without overwhelming:

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

Line 1 breakdown:

• [Opus] — Active model badge, colored via colors.model (default cyan)
• │ — Separator
• my-project — Project path, depth controlled by pathLevels (1-3)
• git:(main*) — Branch name with dirty indicator (* = uncommitted changes)

Line 2 breakdown:

• Context █████░░░░░ 45% — Visual bar showing 45% context consumption, green→yellow→red gradient
• │ — Separator between context and usage
• Usage ██░░░░░░░░ 25% (1h 30m / 5h) — Rate limit consumption with reset countdown

This compact format is achieved through the elementOrder and mergeGroups configuration system, which determines which elements appear and how they share line space.

Example 2: Advanced Configuration with Full Feature Set

Here's the repository's example configuration demonstrating extensive customization:

{
  "language": "zh",
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "memory", "environment", "agents", "todos", "sessionTime"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showConfigCounts": true,
    "showDuration": true,
    "showMemoryUsage": true
  },
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "#FF6600"
  }
}

Key configuration insights:

• "language": "zh" — Switches all HUD labels to Chinese; English remains default
• "lineLayout": "expanded" — Enables multi-line display (alternative: "compact" for single line)
• "elementOrder" — Precisely controls display sequence; omit elements to hide them
• "gitStatus.showFileStats": true — Enables !3 +1 ?2 style change counters
• "display.showMemoryUsage": true — Opts into approximate system RAM monitoring
• "colors.custom": "#FF6600" — Demonstrates hex color support beyond named colors

Example 3: External Usage Fallback Snapshot

For environments where Claude Code doesn't provide native rate_limits data, Claude HUD supports a local snapshot file:

{
  "updated_at": "2026-04-20T12:00:00.000Z",
  "five_hour": {
    "used_percentage": 42,
    "resets_at": "2026-04-20T15:00:00.000Z"
  },
  "seven_day": {
    "used_percentage": 84,
    "resets_at": "2026-04-27T12:00:00.000Z"
  }
}

Implementation pattern:

• Set display.externalUsagePath to this file's location
• Configure display.externalUsageFreshnessMs (default 300000ms = 5 minutes) to ignore stale data
• Claude HUD prefers stdin rate_limits when available; this fallback only activates when native data is absent
• The balance_label field (not shown) supports prepaid provider balance display

This architecture enables proxy-based usage tracking or custom metering systems without modifying Claude HUD's core logic.

Example 4: Development Build Commands

For contributors or those running bleeding-edge versions:

# Clone the repository
git clone https://github.com/jarrodwatts/claude-hud
cd claude-hud

# Install dependencies and build
npm ci && npm run build

# Run test suite
npm test

The npm ci ensures reproducible builds using package-lock.json. The build process compiles TypeScript sources and validates plugin manifest compatibility with Claude Code's API requirements.

Advanced Usage & Best Practices

Preset Selection Strategy

Start with the Essential preset — it shows activity lines plus git status without overwhelming information density. Graduate to Full only when you genuinely need all data streams simultaneously. Minimal excels for screen recordings or presentations where clean aesthetics matter.

Context Bar Threshold Tuning

The default color transitions (green → yellow → red) use sensible defaults, but customize colors.warning and colors.critical to match your terminal theme. If you frequently operate near context limits, consider setting display.showTokenBreakdown to true for granular visibility above 85% usage.

Prompt Cache Optimization

Enable display.showPromptCache with display.promptCacheTtlSeconds tuned to your subscription tier: 300 (5 minutes) for Pro, 3600 (1 hour) for Max. This countdown helps you time requests to maximize cache hits and minimize API costs.

Git Status Hygiene

Configure gitStatus.pushWarningThreshold and gitStatus.pushCriticalThreshold to surface unpushed commit risks. A threshold of 3 with warning coloring prevents the "oh no, I have 47 unpushed commits" discovery.

Performance Considerations

The maxWidth and forceMaxWidth options solve edge cases with terminal width detection failures. Set maxWidth to your typical terminal width and enable forceMaxWidth only if automatic detection consistently fails in your environment (common in certain tmux/screen configurations).

Comparison with Alternatives

The verdict: Claude HUD occupies a unique position — more powerful than built-in status commands, more integrated than external monitoring, and more maintainable than custom solutions. The only reason to avoid it is if you're running Claude Code in an environment where plugins are prohibited.

FAQ

Is Claude HUD officially supported by Anthropic?

Claude HUD uses Claude Code's officially-documented plugin and statusline APIs. It's a third-party open-source project, not an Anthropic product, but it follows supported extension patterns.

Will this slow down my Claude Code sessions?

No measurable impact. The ~300ms update cycle runs asynchronously, and the plugin's JSON parsing is highly optimized. Claude Code's native performance characteristics remain unchanged.

Can I use Claude HUD with API-key-only access?

Yes, but rate limit display requires Claude subscriber authentication. All other features (context, tools, agents, todos, git) work regardless of access tier.

How do I troubleshoot missing HUD elements?

Tool, agent, and todo lines are hidden by default — enable via /claude-hud:configure or direct config edits. If the entire HUD is missing, ensure you've fully restarted Claude Code after setup. Check ~/.claude/plugins/claude-hud/config.json for JSON syntax errors.

Does this work with remote/SSH Claude Code sessions?

Yes. Claude HUD operates entirely within the Claude Code process. As long as the plugin installs successfully on the remote host, functionality is identical to local usage.

Can I contribute to Claude HUD development?

Absolutely. Clone the repository, run npm ci && npm run build && npm test, and see CONTRIBUTING.md for guidelines.

Is there a performance cost to enabling all display options?

Negligible. Even the "Full" preset with memory usage and all activity lines adds minimal overhead. The heaviest operation — transcript parsing for tool/agent states — runs efficiently with incremental updates.

Conclusion

Claude Code is transformative for software development, but its minimal interface becomes a constraint at scale. Claude HUD eliminates that constraint — replacing opacity with transparency, anxiety with confidence, and guesswork with precision.

After weeks of daily use, I can't imagine returning to uninstrumented Claude Code sessions. The context bar alone has saved me from multiple catastrophic truncation events. The agent visibility transformed how I delegate complex research tasks. And the rate limit tracking lets me optimize my workflow around Anthropic's windows instead of hitting walls unexpectedly.

The installation is trivial. The configuration is deep. The impact is immediate.

Stop flying blind. Install Claude HUD today.

⭐ Star the repository on GitHub — and if it transforms your workflow like it did mine, spread the word to your fellow Claude Code users.

License: MIT | Requirements: Claude Code v1.0.80+, Node.js 18+ (or Bun on macOS/Linux)