Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jarrodwatts/claude-hud/llms.txt

Use this file to discover all available pages before exploring further.

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