/setup

Note: Placeholders like {RUNTIME_PATH}, {SOURCE}, and {GENERATED_COMMAND} should be substituted with actual detected values.

Step 0: Detect Ghost Installation (Run First)

Check for inconsistent plugin state that can occur after failed installations:

macOS/Linux:

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

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

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

echo "Cache: $CACHE_EXISTS | Registry: $REGISTRY_EXISTS | Temp: ${TEMP_FILES:-none}"

Windows (PowerShell):

$cache = Test-Path "$env:USERPROFILE\.claude\plugins\cache\claude-hud"
$registry = (Get-Content "$env:USERPROFILE\.claude\plugins\installed_plugins.json" -ErrorAction SilentlyContinue) -match "claude-hud"
$temp = Get-ChildItem "$env:USERPROFILE\.claude\plugins\cache\temp_local_*" -ErrorAction SilentlyContinue
Write-Host "Cache: $cache | Registry: $registry | Temp: $($temp.Count) files"

Interpreting Results

Cache	Registry	Meaning	Action
YES	YES	Normal install (may still be broken)	Continue to Step 1
YES	NO	Ghost install - cache orphaned	Clean up cache
NO	YES	Ghost install - registry stale	Clean up registry
NO	NO	Not installed	Continue to Step 1

If temp files exist, a previous install was interrupted. Clean them up.

Cleanup Commands

If ghost installation detected, ask user if they want to reset. If yes:

macOS/Linux:

# Remove orphaned cache
rm -rf ~/.claude/plugins/cache/claude-hud

# Remove temp files from failed installs
rm -rf ~/.claude/plugins/cache/temp_local_*

# Reset registry (removes ALL plugins - warn user first!)
# Only run if user confirms they have no other plugins they want to keep:
echo '{"version": 2, "plugins": {}}' > ~/.claude/plugins/installed_plugins.json

Windows (PowerShell):

# Remove orphaned cache
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\cache\claude-hud" -ErrorAction SilentlyContinue

# Remove temp files
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\cache\temp_local_*" -ErrorAction SilentlyContinue

# Reset registry (removes ALL plugins - warn user first!)
'{"version": 2, "plugins": {}}' | Set-Content "$env:USERPROFILE\.claude\plugins\installed_plugins.json"

After cleanup, tell user to restart Claude Code and run /plugin install claude-hud again.

Linux: Cross-Device Filesystem Check

On Linux only, if install keeps failing, check for EXDEV issue:

[ "$(df --output=source ~ /tmp 2>/dev/null | tail -2 | uniq | wc -l)" = "2" ] && echo "CROSS_DEVICE"

If this outputs CROSS_DEVICE, /tmp and home are on different filesystems. This causes EXDEV: cross-device link not permitted during installation. Workaround:

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

This is a Claude Code platform limitation.

---

Step 1: Detect Platform & Runtime

IMPORTANT: Determine the platform from your environment context (Platform: value), NOT from uname -s. The Bash tool may report a different environment than the user's actual platform (e.g., Git Bash on Windows reports MINGW even when the user launched Claude Code from PowerShell).

Platform	Command Format
darwin	bash (macOS)
linux	bash (all Linux distros including NixOS, Ubuntu, Arch, etc.)
win32	PowerShell (works universally on Windows 10+)

---

macOS/Linux (Platform: darwin or linux):

1. Get plugin path:

   ls -td ~/.claude/plugins/cache/claude-hud/claude-hud/*/ 2>/dev/null | head -1
   

   If empty, the plugin is not installed. Go back to Step 0 to check for ghost installation or EXDEV issues. If Step 0 was clean, tell user to install via /plugin install claude-hud first.

2. Get runtime absolute path (prefer bun for performance, fallback to node):

   command -v bun 2>/dev/null || command -v node 2>/dev/null
   

   If empty, stop and tell user to install Node.js or Bun.

3. Verify the runtime exists:

   ls -la {RUNTIME_PATH}
   

   If it doesn't exist, re-detect or ask user to verify their installation.

4. Determine source file based on runtime:

   basename {RUNTIME_PATH}
   

   If result is "bun", use src/index.ts (bun has native TypeScript support). Otherwise use dist/index.js (pre-compiled).

5. Generate command (quotes around runtime path handle spaces):

   bash -c '"{RUNTIME_PATH}" "$(ls -td ~/.claude/plugins/cache/claude-hud/claude-hud/*/ 2>/dev/null | head -1){SOURCE}"'
   

Windows (Platform: win32):

1. Get plugin path:

   (Get-ChildItem "$env:USERPROFILE\.claude\plugins\cache\claude-hud\claude-hud" | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName
   

   If empty or errors, the plugin is not installed. Tell user to install via marketplace first.

2. Get runtime absolute path (prefer bun, fallback to node):

   if (Get-Command bun -ErrorAction SilentlyContinue) { (Get-Command bun).Source } elseif (Get-Command node -ErrorAction SilentlyContinue) { (Get-Command node).Source } else { Write-Error "Neither bun nor node found" }
   

   If neither found, stop and tell user to install Node.js or Bun.

3. Check if runtime is bun (by filename). If bun, use src\index.ts. Otherwise use dist\index.js.

4. Generate command (note: quotes around runtime path handle spaces in paths):

   powershell -Command "& {$p=(Get-ChildItem $env:USERPROFILE\.claude\plugins\cache\claude-hud\claude-hud | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName; & '{RUNTIME_PATH}' (Join-Path $p '{SOURCE}')}"
   

WSL (Windows Subsystem for Linux): If running in WSL, use the macOS/Linux instructions. Ensure the plugin is installed in the Linux environment (~/.claude/plugins/...), not the Windows side.

Step 2: Test Command

Run the generated command. It should produce output (the HUD lines) within a few seconds.

• If it errors, do not proceed to Step 3.
• If it hangs for more than a few seconds, cancel and debug.
• This test catches issues like broken runtime binaries, missing plugins, or path problems.

Step 3: Apply Configuration

Read the settings file and merge in the statusLine config, preserving all existing settings:

• macOS/Linux/Git Bash: ~/.claude/settings.json
• Windows (native PowerShell): $env:USERPROFILE\.claude\settings.json

If the file doesn't exist, create it. If it contains invalid JSON, report the error and do not overwrite. If a write fails with File has been unexpectedly modified, re-read the file and retry the merge once.

{
  "statusLine": {
    "type": "command",
    "command": "{GENERATED_COMMAND}"
  }
}

Note: The generated command dynamically finds and runs the latest installed plugin version. Updates are automatic - no need to re-run setup after plugin updates. If the HUD suddenly stops working, re-run /claude-hud:setup to verify the plugin is still installed.

Step 4: Verify With User

Use AskUserQuestion:

• Question: "The HUD should now appear below your input field. Is it working?"
• Options: "Yes, I see it" / "No, something's wrong"

If yes: Ask the user if they'd like to ⭐ star the claude-hud repository on GitHub to support the project. If they agree and gh CLI is available, run: gh api -X PUT /user/starred/jarrodwatts/claude-hud. Only run the star command if they explicitly say yes.

If no: Debug systematically:

1. Verify config was applied:

   • Read settings file (~/.claude/settings.json or $env:USERPROFILE\.claude\settings.json on Windows)
   • Check statusLine.command exists and looks correct
   • If command contains a hardcoded version path (not using dynamic ls -td lookup), it may be a stale config from a previous setup

2. Test the command manually and capture error output:

   {GENERATED_COMMAND} 2>&1
   

3. Common issues to check:

   "command not found" or empty output:

   • Runtime path might be wrong: ls -la {RUNTIME_PATH}
   • On macOS with mise/nvm/asdf: the absolute path may have changed after a runtime update
   • Symlinks may be stale: command -v node often returns a symlink that can break after version updates
   • Solution: re-detect with command -v bun or command -v node, and verify with realpath {RUNTIME_PATH} (or readlink -f {RUNTIME_PATH}) to get the true absolute path

   "No such file or directory" for plugin:

   • Plugin might not be installed: ls ~/.claude/plugins/cache/claude-hud/
   • Solution: reinstall plugin via marketplace

   Windows: "bash not recognized":

   • Wrong command type for Windows
   • Solution: use the PowerShell command variant

   Windows: PowerShell execution policy error:

   • Run: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

   Permission denied:

   • Runtime not executable: chmod +x {RUNTIME_PATH}

   WSL confusion:

   • If using WSL, ensure plugin is installed in Linux environment, not Windows
   • Check: ls ~/.claude/plugins/cache/claude-hud/

4. If still stuck: Show the user the exact command that was generated and the error, so they can report it or debug further