Skip to main content
The /claude-hud:setup command configures Claude HUD as your statusline. It detects your platform, shell, and runtime; locates the plugin; generates the correct command; writes it to ~/.claude/settings.json; and optionally enables extra display features.
After setup writes the config, you must restart Claude Code for the statusLine to take effect. Quit and run claude again in your terminal, then re-run /claude-hud:setup to complete the verification step.

​
What gets written

Setup merges the following into ~/.claude/settings.json, preserving all existing settings: 
{
  "statusLine": {
    "type": "command",
    "command": "<generated command>"
  }
}
The generated command dynamically finds and runs the latest installed plugin version at runtime. You do not need to re-run setup after plugin updates — the command auto-detects the newest version on every invocation.

​
Setup flow

1

Detect ghost installation

Before anything else, setup checks for an inconsistent plugin state that can occur after a failed or interrupted installation.A ghost installation is a mismatch between the plugin cache and the registry:
CacheRegistryMeaningAction
PresentPresentNormal (may still be broken)Continue
PresentMissingGhost — cache orphanedClean up cache
MissingPresentGhost — registry staleClean up registry
MissingMissingNot installedContinue
If temp files from an interrupted install exist under ~/.claude/plugins/cache/temp_local_*, those are cleaned up too.
CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"

# Check 1: Cache exists?
CACHE_EXISTS=$(ls -d "$CLAUDE_DIR/plugins/cache/claude-hud" 2>/dev/null && echo "YES" || echo "NO")

# Check 2: Registry entry exists?
REGISTRY_EXISTS=$(grep -q "claude-hud" "$CLAUDE_DIR/plugins/installed_plugins.json" 2>/dev/null && echo "YES" || echo "NO")

# Check 3: Temp files left behind?
TEMP_FILES=$(ls -d "$CLAUDE_DIR/plugins/cache/temp_local_"* 2>/dev/null | head -1)

echo "Cache: $CACHE_EXISTS | Registry: $REGISTRY_EXISTS | Temp: ${TEMP_FILES:-none}"
If a ghost installation is detected, clean it up:
CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"

# Remove orphaned cache
rm -rf "$CLAUDE_DIR/plugins/cache/claude-hud"

# Remove temp files from failed installs
rm -rf "$CLAUDE_DIR/plugins/cache/temp_local_"*

# Reset registry (removes ALL plugins — only run if confirmed)
echo '{"version": 2, "plugins": {}}' > "$CLAUDE_DIR/plugins/installed_plugins.json"
Resetting the registry removes all plugins, not just claude-hud. Only do this if you have no other plugins you want to keep.
After cleanup, restart Claude Code and reinstall via /plugin install claude-hud.

​
Linux: cross-device filesystem issue

On Linux, /tmp is often a separate filesystem (tmpfs). This causes plugin installation to fail with EXDEV: cross-device link not permitted. This is a Claude Code platform limitation.Workaround — set TMPDIR to a path on the same filesystem as your home directory before installing:
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude /plugin install claude-hud
To check whether your system is affected:
[ "$(df --output=source ~ /tmp 2>/dev/null | tail -2 | uniq | wc -l)" = "2" ] && echo "CROSS_DEVICE"
If the output is CROSS_DEVICE, use the TMPDIR workaround above.
2

Detect platform, shell, and runtime

Setup reads the environment context (Platform: and Shell:) to determine which command format to generate.
PlatformShellFormat
darwinanybash (macOS)
linuxanybash (Linux)
win32bash (Git Bash, MSYS2)bash (same as macOS/Linux)
win32powershell, pwsh, or cmdPowerShell
  1. Find the plugin installation path (sorted by version, not modification time): 
    ls -d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/claude-hud/claude-hud/*/ 2>/dev/null \
  | awk -F/ '{ print $(NF-1) "\t" $0 }' \
  | sort -t. -k1,1n -k2,2n -k3,3n -k4,4n \
  | tail -1 | cut -f2-
  2. Find the runtime (bun preferred for performance, node as fallback): 
    command -v bun 2>/dev/null || command -v node 2>/dev/null
  3. Determine the source file — if the runtime is bun, use src/index.ts (native TypeScript support); otherwise use dist/index.js (pre-compiled).
  4. The generated command uses dynamic version detection so it always runs the latest installed version: 
    bash -c 'plugin_dir=$(ls -d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/claude-hud/claude-hud/*/ 2>/dev/null | awk -F/ '"'"'{ print $(NF-1) "\t" $0 }'"'"' | sort -t. -k1,1n -k2,2n -k3,3n -k4,4n | tail -1 | cut -f2-); exec "{RUNTIME_PATH}" "${plugin_dir}{SOURCE}"'
If neither bun nor node is found, install Node.js or Bun before continuing.
3

Test the generated command

Setup runs the generated command to verify it produces output within a few seconds. This catches broken runtime binaries, missing plugins, or path problems before writing anything to settings.json.If the command errors or hangs, setup stops here and does not proceed to write the config.
4

Write statusLine config

Setup reads ~/.claude/settings.json, merges in the statusLine block, and writes it back — preserving all existing settings.
Config path: ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "<generated command>"
  }
}
If settings.json does not exist, it is created. If it contains invalid JSON, setup reports the error and does not overwrite.
After this step, restart Claude Code — quit and run claude again in your terminal. The HUD cannot appear in the same session where setup was run. Once restarted, re-run /claude-hud:setup to continue to the optional features step and verify the HUD is working.
5

Enable optional features

After the statusLine is applied, setup offers opt-in display features. All are hidden by default.
FeatureWhat it showsConfig key
Tools activity◐ Edit: file.ts | ✓ Read ×3display.showTools: true
Agents & TodosSubagent status and todo progressdisplay.showAgents: true, display.showTodos: true
Session infoSession duration and config counts (CLAUDE.md, rules, MCPs)display.showDuration: true, display.showConfigCounts: true
Session nameSession slug or custom title from /renamedisplay.showSessionName: true
Custom lineA custom phrase of your choice (max 80 chars)display.customLine: "<your text>"
Selected options are written to ~/.claude/plugins/claude-hud/config.json. Only enabled keys are written — unselected items are left to their defaults.
6

Verify the HUD is working

Setup confirms you have restarted Claude Code, then asks whether the HUD is visible below the input field.If the HUD is not appearing, work through the following:
  1. Restart Claude Code — this is the most common cause. Quit completely and run claude again.
  2. Verify the config was applied — read ~/.claude/settings.json and confirm statusLine.command is present and correct. A stale config with a hardcoded version path (rather than the dynamic lookup command) indicates a previous setup run.
  3. Test the command manually and capture any error output: 
    <generated command> 2>&1
  4. Common issues:
    • command not found or empty output — the runtime path may be stale (common with mise/nvm/asdf after a version update). Re-detect with command -v bun or command -v node, and resolve symlinks with realpath or readlink -f.
    • No such file or directory for the plugin — the plugin may not be installed. Reinstall via /plugin install claude-hud.
    • Windows shell mismatch — the command format does not match the detected shell. Re-run the detection step.
    • Windows PowerShell execution policy error — run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned.
    • Permission denied — the runtime may not be executable: chmod +x <runtime path>.
    • WSL confusion — if using WSL, ensure the plugin is installed in the Linux environment (~/.claude/plugins/...), not the Windows side.

Build docs developers (and LLMs) love

Get started for freeTalk to us