claude-hud/CLAUDE.README.md

Claude HUD

Real-time statusline showing context usage, active tools, running agents, and todo progress.

---

For Humans

Step 1: Add the marketplace

/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the plugin

/plugin install claude-hud

Step 3: Configure the statusline

/claude-hud:setup

Done. The HUD appears immediately — no restart needed.

---

For LLM Agents

If you're an LLM agent helping a user install or work with Claude HUD, follow these steps.

<agent_workflow>

Step 1: Check Prerequisites

Verify Claude Code version is 1.0.80 or later:

claude --version

If not installed or outdated, direct user to https://claude.ai/code

Step 2: Add the Marketplace

Run this command in Claude Code:

/plugin marketplace add jarrodwatts/claude-hud

Step 3: Install the Plugin

Run this command in Claude Code:

/plugin install claude-hud

Step 4: Configure the Statusline

Run this command in Claude Code:

/claude-hud:setup

This adds the statusLine configuration to the user's settings.json.

Step 5: Inform User

Tell the user:

• Installation complete
• The statusline appears immediately — no restart needed
• It shows: context usage, active tools, running agents, and todo progress

Step 6: Ask About Starring (Optional)

Ask the user: "Would you like to star the repository to support the project?"

Only if they explicitly agree, run:

gh repo star jarrodwatts/claude-hud

Never run this automatically without user consent.

</agent_workflow>

---

Reference

Technical documentation for agents who need to understand, modify, or debug Claude HUD.

Claude HUD Real-time statusline showing context usage, active tools, running agents, and todo progress. Always visible below your input, zero config required. github.com/jarrodwatts/claude-hud MIT Node.js 18+ or Bun v1.0.80 or later TypeScript 5, ES2022 target, NodeNext modules Claude HUD is a statusline plugin invoked by Claude Code every ~300ms. It reads data from two sources, renders up to 4 lines, and outputs to stdout.

<data_flow> Claude Code invokes the plugin → Plugin reads JSON from stdin (model, context, tokens) → Plugin parses transcript JSONL file (tools, agents, todos) → Plugin reads config files (MCPs, hooks, rules) → Plugin renders lines to stdout → Claude Code displays the statusline </data_flow>

<data_sources> <stdin_json description="Native accurate data from Claude Code"> Current model name (Opus, Sonnet, Haiku) Current token count Maximum context size Path to session transcript JSONL file Current working directory </stdin_json>

<transcript_jsonl description="Parsed from transcript file">
  <item>tool_use blocks → tool name, target file, start time</item>
  <item>tool_result blocks → completion status, duration</item>
  <item>Running tools = tool_use without matching tool_result</item>
  <item>TodoWrite calls → current todo list</item>
  <item>Task calls → agent type, model, description</item>
</transcript_jsonl>

<config_files description="Read from Claude configuration">
  <item>~/.claude/settings.json → mcpServers count, hooks count</item>
  <item>CLAUDE.md files in cwd and ancestors → rules count</item>
  <item>.mcp.json files → additional MCP count</item>
</config_files>

</data_sources>

<file_structure> Reads stdin, parses transcript, counts configs, calls render. Exports main() for testing with dependency injection. Reads and validates Claude Code's JSON input. Returns StdinData with model, context, transcript_path. Parses the session transcript file line by line. Extracts tools, agents, todos, and session start time. Matches tool_use to tool_result by ID to calculate status. Counts CLAUDE.md files, rules, MCP servers, and hooks. Searches cwd, ~/.claude/, and project .claude/ directories. Reads config.json from ~/.claude/plugins/claude-hud/. Validates and merges user settings with defaults. Exports HudConfig interface and loadConfig function. Gets branch name, dirty state, and ahead/behind counts. Uses execFile with array args for safe command execution. Reads OAuth credentials from ~/.claude/.credentials.json. Calls api.anthropic.com/api/oauth/usage endpoint (opt-in). Caches results (60s success, 15s failure). StdinData, ToolEntry, AgentEntry, TodoItem, TranscriptData, RenderContext.

Calls each line renderer and outputs to stdout. Conditionally shows lines based on data presence. Renders: [Model | Plan] █████░░░░░ 45% | project git:(branch) | 2 CLAUDE.md | 5h: 25% | ⏱️ 5m Context bar colors: green (<70%), yellow (70-85%), red (>85%). Renders: ◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 Shows running tools with spinner, completed tools aggregated. Renders: ◐ explore [haiku]: Finding auth code (2m 15s) Shows agent type, model, description, elapsed time. Renders: ▸ Fix authentication bug (2/5) Shows current in_progress task and completion count. Functions: green(), yellow(), red(), dim(), bold(), reset(). Used for colorizing output based on status/thresholds.

<output_format> [Model | Plan] █████░░░░░ 45% | project git:(branch) | 2 CLAUDE.md | 5h: 25% | ⏱️ 5m ◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 ◐ explore [haiku]: Finding auth code (2m 15s) ▸ Fix authentication bug (2/5) </output_format>

<context_thresholds> </context_thresholds>

<plugin_configuration> .claude-plugin/plugin.json <manifest_content> { "name": "claude-hud", "description": "Real-time statusline HUD for Claude Code", "version": "0.0.1", "author": { "name": "Jarrod Watts", "url": "https://github.com/jarrodwatts" } } </manifest_content> The plugin.json contains metadata only. statusLine is NOT a valid plugin.json field.

<statusline_config> The /claude-hud:setup command adds statusLine to ~/.claude/settings.json with an auto-updating command that finds the latest installed version. Updates are automatic - no need to re-run setup after updating the plugin. </statusline_config> </plugin_configuration>

git clone https://github.com/jarrodwatts/claude-hud cd claude-hud npm ci npm run build

<test_commands> npm test # Run all tests npm run build # Compile TypeScript to dist/ </test_commands>

<manual_testing> # 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

# Test with transcript path:
echo '{"model":{"display_name":"Sonnet"},"transcript_path":"/path/to/transcript.jsonl","context_window":{"current_usage":{"input_tokens":90000},"context_window_size":200000}}' | node dist/index.js

</manual_testing>

Add new data extraction in transcript.ts or stdin.ts Add new interface fields in types.ts Create new render file in src/render/ or modify existing Update src/render/index.ts to include new line Run npm run build and test

<modifying_thresholds> Edit src/render/session-line.ts to change context threshold values. Look for the percentage checks that determine color coding. </modifying_thresholds>

<adding_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 </adding_new_line>

Plugin not installed or statusLine not configured Run: /plugin marketplace add jarrodwatts/claude-hud Run: /plugin install claude-hud Run: /claude-hud:setup Ensure Claude Code is v1.0.80 or later No stdin data received (normal on first invocation) This is expected briefly on startup, should resolve automatically Data comes directly from Claude Code - it's accurate The percentage is (input_tokens / context_window_size) * 100 No tools used yet or transcript not being parsed Lines only appear when there's data to show Ensure Node.js 18+ installed Run npm ci to reinstall dependencies Delete dist/ and node_modules/, then npm ci && npm run build

<key_interfaces> transcript_path?: string cwd?: string model?: { id?: string, display_name?: string } context_window?: { context_window_size?: number, current_usage?: { input_tokens?: number } }

id: string name: string target?: string status: 'running' | 'completed' | 'error' startTime: Date endTime?: Date id: string type: string model?: string description?: string status: 'running' | 'completed' startTime: Date endTime?: Date content: string status: 'pending' | 'in_progress' | 'completed' stdin: StdinData transcript: TranscriptData claudeMdCount: number rulesCount: number mcpCount: number hooksCount: number sessionDuration: string

<task_instructions> Follow the agent_workflow steps above.

If the user wants to modify Claude HUD: 1. Clone the repo or navigate to the plugin directory 2. Make changes following the file_structure section 3. Run npm run build to compile 4. Restart Claude Code to see changes If the user reports issues: 1. Check troubleshooting section first 2. Verify Claude Code version (needs v1.0.80+) 3. Check if plugin is listed: claude /plugin list 4. Test manually with echo command from development section If the user asks how something works: 1. Reference the architecture and data_flow sections 2. Point to specific files in file_structure 3. Explain the data sources and how they're combined