Claude HUD

Skill by

ara.so

— Daily 2026 Skills collection.

Claude HUD is a Claude Code plugin that adds a persistent statusline to your terminal showing real-time context window usage, active tool calls, running subagents, and todo progress — always visible below your input prompt.

What It Does

Feature

Description

Context health

Visual bar showing how full your context window is (green → yellow → red)

Tool activity

Live display of file reads, edits, and searches as they happen

Agent tracking

Shows which subagents are running and what they're doing

Todo progress

Real-time task completion tracking

Usage limits

Claude subscriber rate limit consumption

Git status

Current branch, dirty state, ahead/behind remote

Requirements

Claude Code v1.0.80+

Node.js 18+ or Bun

Installation

Run these commands inside a Claude Code session:

Step 1: Add the marketplace

/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the plugin

/plugin install claude-hud

Linux users

If you get

EXDEV: cross-device link not permitted

, set TMPDIR first:

mkdir

-p

~/.cache/tmp

&&

TMPDIR

=~

/.cache/tmp claude

Step 3: Configure the statusline

/claude-hud:setup

Windows users

If setup reports no JavaScript runtime, install Node.js LTS first: winget install OpenJS . NodeJS . LTS Step 4: Restart Claude Code to load the new statusLine config. What You See Default 2-line layout [Opus] │ my-project git:(main) Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) With optional lines enabled [Opus] │ my-project git:(main) Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) ◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 ◐ explore [haiku]: Finding auth code (2m 15s) ▸ Fix authentication bug (2/5) Configuration Interactive configuration (recommended) /claude-hud:configure This opens a guided flow with preset options: Preset Shows Full Everything — tools, agents, todos, git, usage, duration Essential Activity lines + git, minimal clutter Minimal Model name and context bar only Manual configuration Edit ~/.claude/plugins/claude-hud/config.json directly: { "lineLayout" : "expanded" , "pathLevels" : 2 , "elementOrder" : [ "project" , "context" , "usage" , "tools" , "agents" , "todos" ] , "gitStatus" : { "enabled" : true , "showDirty" : true , "showAheadBehind" : true , "showFileStats" : false } , "display" : { "showModel" : true , "showContextBar" : true , "contextValue" : "percent" , "showUsage" : true , "usageBarEnabled" : true , "showTools" : true , "showAgents" : true , "showTodos" : true , "showDuration" : false , "showSpeed" : false , "showConfigCounts" : false , "showMemoryUsage" : false , "showSessionName" : false , "showClaudeCodeVersion" : false , "sevenDayThreshold" : 80 , "showTokenBreakdown" : true } , "colors" : { "context" : "green" , "usage" : "brightBlue" , "warning" : "yellow" , "usageWarning" : "brightMagenta" , "critical" : "red" , "model" : "cyan" , "project" : "yellow" , "git" : "magenta" , "gitBranch" : "cyan" , "label" : "dim" , "custom" : "208" } } Key Configuration Options Layout { "lineLayout" : "expanded" , // "expanded" (multi-line) or "compact" (single line) "pathLevels" : 1 // 1-3 directory levels in project path } Path level examples: 1 → [Opus] │ my-project git:(main) 2 → [Opus] │ apps/my-project git:(main) 3 → [Opus] │ dev/apps/my-project git:(main) Context display formats { "display" : { "contextValue" : "percent" // "45%" // "contextValue": "tokens" // "45k/200k" // "contextValue": "remaining" // "55% remaining" // "contextValue": "both" // "45% (45k/200k)" } } Element ordering (expanded layout) { "elementOrder" : [ "project" , "context" , "usage" , "memory" , "environment" , "tools" , "agents" , "todos" ] } Omit any entry from the array to hide it entirely. Git status options { "gitStatus" : { "enabled" : true , "showDirty" : true , // "main" for uncommitted changes "showAheadBehind" : true , // "main ↑2 ↓1" "showFileStats" : true // "main !3 +1 ?2" (modified/added/deleted/untracked) } } Colors Supported values: named colors ( dim , red , green , yellow , magenta , cyan , brightBlue , brightMagenta ), 256-color numbers ( 0-255 ), or hex (

rrggbb

). { "colors" : { "context" : "#00FF88" , "model" : "208" , "project" : "#FF6600" } } How It Works Claude HUD uses Claude Code's native statusline API — no separate window, no tmux needed: Claude Code → stdin JSON → claude-hud → stdout → terminal statusline ↘ transcript JSONL (tools, agents, todos parsed live) Token data comes directly from Claude Code (not estimated) Scales with reported context window size including 1M-context sessions Parses transcript for tool/agent activity Updates every ~300ms Common Patterns Minimal setup for focused work { "lineLayout" : "compact" , "display" : { "showModel" : true , "showContextBar" : true , "contextValue" : "percent" , "showUsage" : false , "showTools" : false , "showAgents" : false , "showTodos" : false } } Full monitoring setup { "lineLayout" : "expanded" , "pathLevels" : 2 , "gitStatus" : { "enabled" : true , "showDirty" : true , "showAheadBehind" : true , "showFileStats" : true } , "display" : { "showTools" : true , "showAgents" : true , "showTodos" : true , "showDuration" : true , "showMemoryUsage" : true , "showConfigCounts" : true , "contextValue" : "both" , "showTokenBreakdown" : true } } Always show 7-day usage { "display" : { "showUsage" : true , "sevenDayThreshold" : 0 } } Output: Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d) Troubleshooting HUD not appearing after setup Fully restart Claude Code (quit and re-run claude in terminal) On macOS, ensure you've fully quit the app, not just closed the window Config not applying Check for JSON syntax errors — invalid JSON silently falls back to defaults Validate: cat ~/.claude/plugins/claude-hud/config.json | node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))" Delete config and run /claude-hud:configure to regenerate Git status missing Verify you're in a git repository ( git status ) Ensure gitStatus.enabled is not false in config Tool/agent/todo lines not showing These are hidden by default — enable with showTools , showAgents , showTodos Lines only render when there's active activity to display Usage limits not showing Requires a Claude subscriber account (not API key only) AWS Bedrock users see Bedrock label; usage is managed in AWS console instead Usage data may be empty until after the first model response in a new session Older Claude Code versions that don't emit rate_limits won't show subscriber usage Linux cross-device error on install mkdir -p ~/.cache/tmp && TMPDIR =~ /.cache/tmp claude

Then run /plugin install claude-hud inside that session

Windows: no JavaScript runtime found winget install OpenJS . NodeJS . LTS

Restart shell, then run /claude-hud:setup again

Plugin Commands Reference Command Description /plugin marketplace add jarrodwatts/claude-hud Register the plugin source /plugin install claude-hud Install the plugin /claude-hud:setup Initial setup wizard, writes statusLine config /claude-hud:configure Interactive configuration with preview Config File Location ~/.claude/plugins/claude-hud/config.json