claude-hud: 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

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 after each interaction (new assistant message, /compact finishing, permission-mode changes, vim-mode toggles), debounced at 300ms — not on a fixed polling loop. 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

From Claude Code stdin rate limits:

• rate_limits.five_hour.used_percentage - 5-hour subscriber usage percentage
• rate_limits.five_hour.resets_at - 5-hour reset timestamp
• rate_limits.seven_day.used_percentage - 7-day subscriber usage percentage
• rate_limits.seven_day.resets_at - 7-day reset timestamp