Claude Hud Statusline

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

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:

bash

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:

powershell

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:

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

Config File Location

~/.claude/plugins/claude-hud/config.json