Skip to main content
The most common cause is that Claude Code has not yet loaded the statusLine config that was written by /claude-hud:setup.Fix: Restart Claude Code.On macOS, fully quit the Claude Code application and run claude again in your terminal.To verify the setup was applied, check that statusLine exists in ~/.claude/settings.json:
cat ~/.claude/settings.json
You should see a statusLine key pointing to the claude-hud script. If it is missing, re-run /claude-hud:setup.To test the command manually, copy the command value from statusLine and run it:
echo '{"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000}}' | <your-statusLine-command>
If you see formatted output, the binary is working. If you see an error, check the runtime path.
Claude HUD silently falls back to defaults when it encounters a config error. Common causes:
  • JSON syntax error — a trailing comma, missing quote, or other invalid JSON causes the entire file to be ignored.
  • Invalid pathLevels — must be 1, 2, or 3. Other values revert to 1.
  • Invalid lineLayout — must be "expanded" or "compact". Other values revert to "expanded".
  • Invalid color name — must be one of: red, green, yellow, magenta, cyan, brightBlue, brightMagenta. You can also use a 256-color index (0–255) or a hex string (#rrggbb).
To reset and start fresh:
rm ~/.claude/plugins/claude-hud/config.json
Then run /claude-hud:configure to regenerate the file.
Git status requires:
  1. You are working inside a git repository.
  2. gitStatus.enabled is not set to false in your config.
Check your current directory:
git rev-parse --abbrev-ref HEAD
If this returns an error, you are not in a git repository. Claude HUD will show no branch info.If you are in a git repository but the branch is still missing, check your config:
cat ~/.claude/plugins/claude-hud/config.json
Ensure gitStatus.enabled is true (or absent — it defaults to true).
These lines are hidden by default. They only appear when:
  1. The corresponding option is enabled in config.
  2. There is activity to display.
Enable them via /claude-hud:configure, or add them manually to ~/.claude/plugins/claude-hud/config.json:
{
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true
  }
}
Even after enabling, the lines only appear when Claude is actively using tools, running agents, or has a todo list. They will not show during idle periods.
Usage display requires a Pro, Max, or Team subscription authenticated with OAuth. It is not available for API key users.Check these conditions:
  • You are logged in with claude (OAuth login), not an API key.
  • Your subscription is Pro, Max, or Team.
  • display.showUsage is not set to false in config.
Usage is automatically hidden when:
  • The model ID indicates AWS Bedrock (the HUD shows Bedrock and skips usage).
  • ANTHROPIC_BASE_URL or ANTHROPIC_API_BASE_URL is set to a non-Anthropic host.
Network issues:If you are behind a proxy, set the appropriate environment variable before running Claude Code:
export HTTPS_PROXY=http://proxy.example.com:8080
HTTP_PROXY, ALL_PROXY, and NO_PROXY are also respected.For high-latency environments, increase the API timeout:
export CLAUDE_HUD_USAGE_TIMEOUT_MS=30000

​
Platform-specific issues

If you use a version manager (mise, nvm, asdf) and recently updated your Node.js runtime, the symlink that the statusLine command points to may be stale.Check the runtime path:
ls -la "$(which node)"
If the path is broken, re-run /claude-hud:setup to regenerate the statusLine command with the current runtime path.
If the HUD command fails on Windows with a script execution error, your PowerShell execution policy may be blocking unsigned scripts.Open PowerShell as Administrator and run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Claude Code in WSL runs in the Linux environment. The plugin must be installed inside WSL, not in the Windows host.Verify the plugin is installed:
ls "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/cache/claude-hud/"
If the directory is missing or empty, run /plugin install claude-hud from within a WSL Claude Code session.

​
Debugging

If the HUD still does not work after the steps above, enable debug output to see what is happening: 
DEBUG=claude-hud claude
This logs the data flow — stdin parsing, transcript reading, usage API calls, and config loading — to stderr. You can also use DEBUG=* to enable all debug output.

Build docs developers (and LLMs) love

Get started for freeTalk to us