claude-hud

Troubleshooting

Fix common issues with Claude HUD installation, display, configuration, and platform-specific quirks. If you run into a problem not covered here, check the GitHub Issues for known bugs and workarounds.

Prerequisites: Claude HUD installed and configured. If you haven’t set it up yet, see Getting Started.

Installation Issues

On Linux, /tmp is often mounted as a separate filesystem (tmpfs). When Claude Code tries to move the plugin from a temp directory to the install location, the cross-device move fails.

Fix: Set TMPDIR to a location on the same filesystem before launching Claude Code:

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

Then install the plugin in that session:

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud

This is a Claude Code platform limitation, not a Claude HUD bug. You only need the TMPDIR workaround during installation — subsequent sessions work normally.

Plugin Install Fails or Times Out

If /plugin install claude-hud hangs or fails:

  1. Check your Claude Code version — Claude HUD requires v1.0.80 or later:
    claude --version
  2. Verify the marketplace is registered:
    /plugin marketplace list
    If jarrodwatts/claude-hud is missing, re-add it:
    /plugin marketplace add jarrodwatts/claude-hud
  3. Check network connectivity — the install fetches the plugin from GitHub. Proxy or firewall rules may block it.
  4. Try a clean install — remove any partial installation and retry:
    /plugin uninstall claude-hud
/plugin install claude-hud

Statusline Not Appearing

If the HUD doesn’t show after installation, work through these checks in order.

Step 1: Verify the Plugin Is Installed 

/plugin list

You should see claude-hud in the output. If not, go back to Getting Started and install it.

Step 2: Run Setup

The statusline needs a configuration entry in ~/.claude/settings.json. Run:

/claude-hud:setup

This registers the statusline command so Claude Code invokes the HUD on every render cycle.

Step 3: Check Claude Code Version

Claude HUD uses the statusline plugin API introduced in Claude Code v1.0.80. Older versions silently ignore the configuration.

claude --version

If your version is below 1.0.80, update Claude Code first.

Step 4: Check for Errors

If the HUD briefly shows [claude-hud] Initializing... and then disappears, the plugin may be crashing. Test it manually:

echo '{"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000}}' | node ~/.claude/plugins/claude-hud/dist/index.js

If this produces output, the plugin itself is working and the issue is in the statusline configuration. If it throws an error, check that Node.js 18+ is installed.

Usage Display Issues

The usage display shows your rate limit consumption for Claude Pro, Max, and Team subscriptions. It appears on the same line as the context bar.

Usage Not Showing

Several conditions can prevent usage data from appearing:

Condition Why Usage Is Hidden
API key authentication Pay-per-token users have no rate limits to display
AWS Bedrock models Usage is managed in AWS, not via Anthropic’s API
Custom ANTHROPIC_BASE_URL The Anthropic OAuth usage API may not apply
display.showUsage: false Explicitly disabled in config

To fix:

  1. Confirm you’re logged in with a Pro, Max, or Team account (not an API key).
  2. Check your config file at ~/.claude/plugins/claude-hud/config.json and ensure display.showUsage is not false.
  3. If you use AWS Bedrock, usage display is intentionally hidden — the HUD shows Bedrock instead.

Usage Shows Stale Data

The HUD caches usage API responses to reduce network calls:

If you need fresher data, lower the cache TTL in your config:

{
  "usage": {
    "cacheTtlSeconds": 30
  }
}

Proxy and Network Issues

If you’re behind a corporate proxy, the usage API call may fail silently. Set the appropriate proxy environment variable:

export HTTPS_PROXY=http://proxy.example.com:8080

You can also use HTTP_PROXY, ALL_PROXY, or NO_PROXY as needed. For high-latency environments, increase the usage API timeout:

export CLAUDE_HUD_USAGE_TIMEOUT_MS=10000

Configuration Problems

Config Not Applying

If your configuration changes aren’t reflected in the HUD:

  1. Check for JSON syntax errors. Invalid JSON silently falls back to defaults. Validate your config file:

    cat ~/.claude/plugins/claude-hud/config.json | python3 -m json.tool

    If this prints an error, fix the JSON syntax.

  2. Verify valid values. Some options have strict allowed values:

    • lineLayout must be "expanded" or "compact"
    • pathLevels must be 1, 2, or 3
    • display.contextValue must be "percent", "tokens", or "remaining"

  3. Regenerate from scratch. Delete the config and use the guided setup:

    rm ~/.claude/plugins/claude-hud/config.json

    Then in Claude Code:

    /claude-hud:configure

Manual Edits Overwritten

Running /claude-hud:configure preserves manual settings like colors.*, pathLevels, and threshold overrides. However, if you see unexpected resets:

Display Issues

Git Status Missing

If the project path shows without a git branch:

  1. Verify you’re in a git repository:
    git rev-parse --is-inside-work-tree
  2. Check that git status is enabled in your config — gitStatus.enabled defaults to true, but may have been set to false.

Tool, Agent, or Todo Lines Not Appearing

These lines are hidden by default. Enable them in your config:

{
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true
  }
}

Or run /claude-hud:configure and choose the Full preset, which enables everything.

Even when enabled, these lines only appear when there’s activity to show:

Context Percentage Seems Wrong

The context percentage comes directly from Claude Code’s native token data — it’s not estimated. The formula is:

(input_tokens / context_window_size) × 100

If the number seems off, consider that:

Token Breakdown at High Context

When context usage exceeds 85%, the HUD automatically shows a token breakdown to help you understand what’s consuming space. This is controlled by display.showTokenBreakdown (default: true).

To disable it:

{
  "display": {
    "showTokenBreakdown": false
  }
}

Platform-Specific Issues

macOS

Claude HUD generally works without issues on macOS. If you experience display problems:

Linux

Beyond the EXDEV installation issue described above:

Windows (WSL)

Claude HUD works in WSL (Windows Subsystem for Linux). The same Linux-specific notes apply:

Getting Help

If none of the solutions above resolve your issue:

  1. Search existing issues: github.com/jarrodwatts/claude-hud/issues
  2. File a new issue with:
    • Your Claude Code version (claude --version)
    • Your Node.js version (node --version)
    • Your operating system and terminal
    • The output of running the manual test command from the “Statusline Not Appearing” section
  3. Check the README for the latest updates: github.com/jarrodwatts/claude-hud