claude-hud-enhanced: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in 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, todo progress, cost tracking, and more.

Build Commands

npm ci               # Install dependencies
npm run build        # Build TypeScript to dist/
npm run dev          # Watch mode for development

# Test (Node.js test runner — requires build first)
npm test             # Run all tests (node --test after build)
npm run test:coverage # Run tests with coverage

# Test (Bun — runs source .ts directly, no build needed)
bun test ./tests/pricing/pricing-models.test.ts

# Manual testing with sample stdin
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 every ~300ms by Claude Code. 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
• rate_limits.* - Subscriber usage limits

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
• Session start time, last response timestamp