claude-hud-statusline

$27

• 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