setup

Setup claude-code-tools HUD

Guide the user through configuring the HUD statusline plugin step by step.

Step 1: Check existing config

Read ~/.claude/plugins/claude-code-tools/hud/config.json to see if there's an existing configuration. If a config already exists, show the user the current settings and ask if they want to reconfigure.

Step 2: Detect runtime

Check if bun is available (run which bun), otherwise fall back to node. Store the runtime choice for the command.

Step 3: Register the statusline

The HUD plugin works by configuring the statusLine field in ~/.claude/settings.json. Claude Code invokes this command every ~300ms, piping session JSON to stdin, and renders stdout as the statusline.

IMPORTANT — auto-update safe path resolution:

The plugin source code is cached at ~/.claude/plugins/cache/claude-code-tools/hud/<version>/. When the plugin updates, a new version directory is created. A hardcoded path would break on update. The statusLine command MUST dynamically resolve to the latest version.

Use this command pattern (replace node with bun if detected):

bash -c '"node" "$(ls -td ~/.claude/plugins/cache/claude-code-tools/hud/*/src/hud.mjs 2>/dev/null | head -1)"'

This finds the most recently modified version directory at runtime, so plugin updates work automatically without re-running setup.

Steps:

1. Read existing ~/.claude/settings.json (create if it doesn't exist).
2. Set the statusLine field to the dynamic command string. Preserve all other existing settings.
3. Write back the updated ~/.claude/settings.json.

Example settings.json entry:

{
  "statusLine": "bash -c '\"node\" \"$(ls -td ~/.claude/plugins/cache/claude-code-tools/hud/*/src/hud.mjs 2>/dev/null | head -1)\"'"
}

Step 4: Configure segments

Ask the user which segments they want to enable. Default is all segments:

• model — Model name (e.g., "Opus 4.6")
• billing — Subscription type badge ([API], [Pro], [Max])
• workspace — Current directory name + worktree indicator
• git — Branch name + diff stats (+insertions/-deletions)
• context — Context window usage bar with percentage
• quota — 5-hour and 7-day rate limit usage (Pro/Max only), with reset countdown
• speed — Output tokens per second
• cost — Estimated session cost (API users)
• agents — Running background agent status