claude-hud-enhanced: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

Claude HUD is a Claude Code plugin that displays a real-time multi-line statusline. It shows context health, tool activity, agent status, and todo progress.

Build Commands

cd plugins/claude-hud-enhanced
npm ci               # Install dependencies
npm run build        # Build TypeScript to dist/

# Test with sample stdin data
echo '{"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000}}' | node dist/index.js

Architecture

Data Flow

Claude Code → stdin JSON → parse → render lines → stdout → Claude Code displays
           ↘ transcript_path → parse JSONL → tools/agents/todos

Key insight: The statusline is invoked by Claude Code on conversation events (new assistant message, /compact, permission-mode/vim-mode change), debounced at 300ms — plus on a fixed timer while idle when statusLine.refreshInterval is set (setup benchmarks the render and writes 2, 5, or 10 — fastest the machine can afford). Without refreshInterval the triggers go quiet while idle and the HUD freezes at its last render. Each invocation:

1. Receives JSON via stdin (model, context, tokens - native accurate data)
2. Parses the transcript JSONL file for tools, agents, and todos
3. Renders multi-line output to stdout
4. Claude Code displays all lines

Data Sources

Native from stdin JSON (accurate, no estimation):

• model.display_name - Current model
• context_window.current_usage - Token counts
• context_window.context_window_size - Max context
• transcript_path - Path to session transcript

From transcript JSONL parsing:

• tool_use blocks → tool name, input, start time
• tool_result blocks → completion, duration
• Running tools = tool_use without matching tool_result
• TodoWrite calls → todo list
• Task calls → agent info

From config files:

• MCP count from ~/.claude/settings.json (mcpServers)
• Hooks count from ~/.claude/settings.json (hooks)
• Rules count from CLAUDE.md files