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

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

Claude HUD

Skill by ara.so — Daily 2026 Skills collection.

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

claude-hud-statusline

Documentation

Documentation

Claude HUD

What It Does

Requirements

Installation

What You See

Default 2-line layout

With optional lines enabled

Configuration

Interactive configuration (recommended)

Manual configuration

Key Configuration Options

Layout

Context display formats

Element ordering (expanded layout)

Git status options

Colors

How It Works

Common Patterns

Minimal setup for focused work

Full monitoring setup

Always show 7-day usage

Troubleshooting

Plugin Commands Reference

Config File Location

Documentation

claude-hud-statusline

Documentation

Claude HUD

What It Does

Requirements

Installation

What You See

Default 2-line layout

With optional lines enabled

Configuration

Interactive configuration (recommended)

Manual configuration

Key Configuration Options

Layout

Context display formats

Element ordering (expanded layout)

Git status options

Colors

How It Works

Common Patterns

Minimal setup for focused work

Full monitoring setup

Always show 7-day usage

Troubleshooting

Plugin Commands Reference

Config File Location