DOCSEARCHbyAlgolia
Submit Docs

Claude HUD

repository·main·Indexed 12 days ago

https://github.com/jarrodwatts/claude-hud

A real-time statusline HUD plugin for Claude Code (v1.0.80+) that provides a persistent display of context window health, active tool usage, running subagents, and task progress. It integrates with Claude Code's native statusline API to monitor token usage, git or Jujutsu (jj) status, and session duration without requiring a separate window.

Tokens
25.3K
Snippets
63
Records
107
Agent score
98%

What's inside Claude HUD

  1. What Claude HUD displays

    main

    Claude HUD provides real-time insights directly below your input line using Claude Code's native statusline API. It tracks:

    • Project Path: Shows your current project directory (depth is configurable).
    • Context Health: Displays how much of the context window remains before it is full.
    • Tool Activity: Real-time monitoring of file reads, edits, and searches.
    • Agent Tracking: Shows which sub-agents are running and their current tasks.
    • Todo Progress: Tracks the completion status of ongoing tasks.

    Display Modes

    Default (2 lines)

    Displays the model/provider, project path, git branch, context progress bar, and usage limits.

    [Opus] │ my-project git:(main*)
上下文 █████░░░░░ 45% │ 使用率 ██░░░░░░░░ 25%（1小时30分 / 5小时）

    Optional Lines (Enabled via /claude-hud:configure)

    You can enable additional lines to see tool activity, agent status, and todo progress:

    ◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← Tool Activity
◐ explore [haiku]: 查找认证代码（2分15秒）       ← Agent Status
▸ 修复认证漏洞（2/5）                             ← Todo Progress

  2. How Claude HUD handles existing statuslines

    main

    To prevent overwriting user configurations, the setup process includes a detection and backup phase. If an existing statusLine is found in settings.json, it is classified to determine the safest course of action:

    Pattern in commandClassificationSource label
    Contains claude-hudReinstall (own config)claude-hud
    Contains claude-paceKnown projectclaude-pace
    Contains cc-statusline or ccstatuslineKnown projectcc-statusline
    Contains statusline.sh, statusline.js, or statusline.pyLikely another statuslinestatusline script
    Any other non-empty valueCustom scriptcustom
    Empty / missing keyClean install(none)

    Behavior based on classification:

    • Clean Install or Reinstall: The setup proceeds automatically (idempotent update).
    • Known Project or Custom Script: The user is prompted to either Replace it with claude-hud (after creating a backup) or Keep the current statusline and exit.

  3. Choose a HUD Preset

    main

    Presets allow you to quickly set up a configuration profile. There are three available presets:

    • Full: Enables everything, including all activity (Tools, Skills, MCP, Agents, Todos), all info (Tokens, Usage, Cost, etc.), Git, and Jujutsu status.
    • Essential: Focuses on activity and Git. Enables Tools, Agents, and Todos; shows Git (with dirty indicator) and Session Duration; disables most other info like Counts, Tokens, and Usage.
    • Minimal (Default): The core experience. Shows only Git (with dirty indicator). Disables all activity and most info elements.

  4. Understand the Claude HUD testing strategy

    main

    The testing strategy for Claude HUD is designed to be fast (<5s) and deterministic, focusing on three distinct layers:

    1. Unit tests: Validates pure helpers (e.g., getContextPercent, getModelName, token/elapsed formatting), render helpers (string assembly/truncation), and transcript parsing (tool/agent/todo aggregation).
    2. Integration tests: Validates CLI behavior by running the CLI with sample stdin JSON and fixture transcripts. Assertions focus on the presence of expected markers (model, percent, tool names) rather than strict line matching to remain resilient to minor formatting changes.
    3. Golden-output tests: Compares full output snapshots against known fixtures to catch subtle UI regressions. Snapshots should only be updated when output changes are intentional.

  5. How Claude HUD works

    main

    Claude HUD integrates directly with Claude Code's native statusline API. It does not require a separate window or tmux.

    It functions by consuming stdin JSON from Claude Code and parsing the transcript JSONL (which contains tool, agent, and todo data) to generate stdout that is displayed in your terminal.

    Key technical details:

    • Data Accuracy: Uses native token data from Claude Code rather than estimates.
    • Context Scaling: Automatically scales with Claude Code's reported context window size (including 1M+ context sessions).
    • Rendering: Re-renders after each interaction (assistant messages, /compact, permission changes, etc.) with a 300ms debounce.

  6. How Jujutsu (jj) status works in Claude HUD

    main

    Claude HUD supports Jujutsu (jj) as an alternative to Git.

    Usage Details:

    • Opt-in: You must set jjStatus.enabled: true in your configuration.
    • Detection: If a .jj directory is found in or above the working directory, HUD will use jj status instead of Git. They are mutually exclusive; it will never show both.
    • Fallback: If jj cannot be queried safely, the HUD falls back to the existing Git status.
    • Safety: The HUD runs jj in a prompt-safe, read-only mode (disabling the pager and ignoring the live working copy) to ensure no repository state is mutated during refreshes.
    • Limitations: Ahead/behind counts and per-file change stats are currently Git-only. jj status includes markers for bookmarks, anonymous changes, dirty working copies, and unresolved conflicts.

  7. How Claude HUD works (Architecture)

    main

    Claude HUD is a statusline plugin invoked by Claude Code after each interaction (debounced at 300ms). It combines data from multiple sources to render up to 4 lines of status information below your input.

    Data Flow

    1. Claude Code invokes the plugin.
    2. Plugin reads JSON from stdin (model, context, tokens).
    3. Plugin parses the session transcript JSONL file (tools, agents, todos).
    4. Plugin reads local configuration files (MCPs, hooks, rules).
    5. Plugin renders lines to stdout.
    6. Claude Code displays the statusline.

    Data Sources

    • stdin JSON: Provides native data like model.display_name, context_window.current_usage.input_tokens, context_window.context_window_size, and transcript_path.
    • Transcript JSONL: Parsed from the session transcript to extract tool_use blocks, tool_result blocks, TodoWrite calls, and Task calls.
    • Config Files: Counts items from ~/.claude/settings.json (MCPs, hooks), CLAUDE.md files (rules), and .mcp.json files.

  8. How Claude HUD handles terminal width (COLUMNS)

    main

    Claude HUD needs to know the terminal width to render correctly. Because Claude Code pipes the subprocess stdout, process.stdout.columns is unavailable at runtime.

    To solve this, the setup process exports the COLUMNS environment variable. The HUD uses the inherited COLUMNS value as the primary source. If COLUMNS is missing or invalid, it falls back to a default of 120.

    Padding Adjustment: The setup command subtracts 4 from the detected COLUMNS value (export COLUMNS=$(( cols > 4 ? cols - 4 : 1 ))) to account for Claude Code's input area padding (2 columns on each side).

  9. Backup and restore settings.json

    main

    The setup process creates a timestamped backup of your settings.json file to protect against corruption and allow for manual recovery.

    Backup Location:

    • macOS/Linux: ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json.bak.YYYYMMDD-HHMMSS
    • Windows: ${CLAUDE_CONFIG_DIR:-$HOME\.claude}\settings.json.bak.YYYYMMDD-HHMMSS

    Restoring a previous command: If you choose to replace an existing statusline, the setup saves the original command to a text file so you can easily restore it later.

    • macOS/Linux: ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/claude-hud/previous-statusline.txt
    • Windows: ${CLAUDE_CONFIG_DIR:-$HOME\.claude}\plugins\claude-hud\previous-statusline.txt

  10. Manual Configuration of Claude HUD

    main

    For advanced overrides that are not available in the guided flow, you can edit the configuration file directly. The guided flow (/claude-hud:configure) is designed to preserve these manual settings while allowing you to change high-level preferences like language or layout.

    Config File Location: ~/.claude/plugins/claude-hud/config.json

    Advanced settings you can override manually:

    • colors.*: Custom colors for various HUD elements.
    • pathLevels: Depth of the project path shown.
    • maxWidth: Fallback width for terminal detection.
    • threshold overrides: For warning/critical colors.
    • display.timeFormat: Formatting for usage windows.
    • display.promptCacheTtlSeconds: TTL for the prompt cache countdown.

  11. Temporarily disable Claude HUD

    main

    If you need to run Claude Code without the HUD for a single session, set the CLAUDE_HUD_DISABLE environment variable to 1. This will cause the HUD to exit immediately without reading session records or performing Git operations, leaving the status line empty.

    CLAUDE_HUD_DISABLE=1 claude

  12. How to extend or modify Claude HUD

    main

    Adding new features

    1. Add new data extraction in src/transcript.ts or src/stdin.ts.
    2. Add new interface fields in src/types.ts.
    3. Create a new render file in src/render/ or modify existing ones.
    4. Update src/render/index.ts to include the new line.
    5. Run npm run build and test.

    Adding a new line

    1. Create src/render/new-line.ts with a render function.
    2. Import and call it from src/render/index.ts.
    3. Add any needed types to src/types.ts.
    4. Add data extraction logic to transcript.ts if needed.

    Modifying thresholds

    Edit src/render/session-line.ts to change the context percentage threshold values used for color coding.