Claude HUD

A Claude Code plugin that shows what's happening — context usage, active tools, running agents, and todo progress. Always visible below your input.

Install

Inside a Claude Code instance, run the following commands:

Step 1: Add the marketplace

/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the plugin

⚠️ Linux users: Click here first

On Linux, /tmp is often a separate filesystem (tmpfs), which causes plugin installation to fail with:

EXDEV: cross-device link not permitted

Fix: Set TMPDIR before installing:

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

Then run the install command below in that session. This is a Claude Code platform limitation.

/plugin install claude-hud

Step 3: Configure the statusline

/claude-hud:setup

⚠️ Windows users: Click here if setup says no JavaScript runtime was found

If setup says no JavaScript runtime was found on Windows, install one for your shell first. The simplest fallback is Node.js LTS:

winget install OpenJS.NodeJS.LTS

Then restart your shell and run /claude-hud:setup again.

Done! Restart Claude Code to load the new statusLine config, then the HUD will appear.

On Windows, make that a full Claude Code restart after setup writes the new statusLine config.

---

What is Claude HUD?

Claude HUD gives you better insights into what's happening in your Claude Code session.

What You See	Why It Matters
Project path	Know which project you're in (configurable 1-3 directory levels)
Context health	Know exactly how full your context window is before it's too late
Tool activity	Watch Claude read, edit, and search files as it happens
Agent tracking	See which subagents are running and what they're doing
Todo progress	Track task completion in real-time

What You See

Default (2 lines)

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

• Line 1 — Model, provider/auth label when relevant (for example Bedrock or API), project path, git branch
• Line 2 — Context bar (green → yellow → red) and usage rate limits

Optional lines (enable via /claude-hud:configure)

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← Tools activity
◐ explore [haiku]: Finding auth code (2m 15s)    ← Agent status
▸ Fix authentication bug (2/5)                   ← Todo progress

---

How It Works

Claude HUD uses Claude Code's native statusline API — no separate window, no tmux required, works in any terminal.

Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal
           ↘ transcript JSONL (tools, agents, todos)

Key features:

• Native token data from Claude Code (not estimated)
• Scales with Claude Code's reported context window size, including newer 1M-context sessions
• Parses the transcript for tool/agent activity
• Updates every ~300ms

---

Configuration

Customize your HUD anytime:

/claude-hud:configure

The guided flow handles layout and display toggles. Advanced overrides such as custom colors and thresholds are preserved there, but you set them by editing the config file directly:

• First time setup: Choose a preset (Full/Essential/Minimal), then fine-tune individual elements
• Customize anytime: Toggle items on/off, adjust git display style, switch layouts
• Preview before saving: See exactly how your HUD will look before committing changes

Presets

Preset	What's Shown
Full	Everything enabled — tools, agents, todos, git, usage, duration
Essential	Activity lines + git status, minimal info clutter
Minimal	Core only — just model name and context bar

After choosing a preset, you can turn individual elements on or off.

Manual Configuration

Edit ~/.claude/plugins/claude-hud/config.json directly for advanced settings such as colors.*, pathLevels, and threshold overrides. Running /claude-hud:configure preserves those manual settings.

Options

Option	Type	Default	Description
lineLayout	string	expanded	Layout: expanded (multi-line) or compact (single line)
pathLevels	1-3	1	Directory levels to show in project path
elementOrder	string[]	["project","context","usage","memory","environment","tools","agents","todos"]	Expanded-mode element order. Omit entries to hide them in expanded mode.
gitStatus.enabled	boolean	true	Show git branch in HUD
gitStatus.showDirty	boolean	true	Show * for uncommitted changes
gitStatus.showAheadBehind	boolean	false	Show ↑N ↓N for ahead/behind remote
gitStatus.showFileStats	boolean	false	Show file change counts !M +A ✘D ?U
display.showModel	boolean	true	Show model name [Opus]
display.showContextBar	boolean	true	Show visual context bar ████░░░░░░
display.contextValue	percent | tokens | remaining | both	percent	Context display format (45%, 45k/200k, 55% remaining, or 45% (45k/200k))
display.showConfigCounts	boolean	false	Show CLAUDE.md, rules, MCPs, hooks counts
display.showDuration	boolean	false	Show session duration ⏱️ 5m
display.showSpeed	boolean	false	Show output token speed out: 42.1 tok/s
display.showUsage	boolean	true	Show Claude subscriber usage limits when available
display.usageBarEnabled	boolean	true	Display usage as visual bar instead of text
display.sevenDayThreshold	0-100	80	Show 7-day usage when >= threshold (0 = always)
display.showTokenBreakdown	boolean	true	Show token details at high context (85%+)
display.showTools	boolean	false	Show tools activity line
display.showAgents	boolean	false	Show agents activity line
display.showTodos	boolean	false	Show todos progress line
display.showSessionName	boolean	false	Show session slug or custom title from /rename
display.showClaudeCodeVersion	boolean	false	Show the installed Claude Code version, e.g. CC v2.1.81
display.showMemoryUsage	boolean	false	Show an approximate system RAM usage line in expanded layout
colors.context	color value	green	Base color for the context bar and context percentage
colors.usage	color value	brightBlue	Base color for usage bars and percentages below warning thresholds
colors.warning	color value	yellow	Warning color for context thresholds and usage warning text
colors.usageWarning	color value	brightMagenta	Warning color for usage bars and percentages near their threshold
colors.critical	color value	red	Critical color for limit-reached states and critical thresholds
colors.model	color value	cyan	Color for the model badge such as [Opus]
colors.project	color value	yellow	Color for the project path
colors.git	color value	magenta	Color for git wrapper text such as git:( and )
colors.gitBranch	color value	cyan	Color for the git branch and branch status text
colors.label	color value	dim	Color for labels and secondary metadata such as Context, Usage, counts, and progress text
colors.custom	color value	208	Color for the optional custom line

Supported color names: dim, red, green, yellow, magenta, cyan, brightBlue, brightMagenta. You can also use a 256-color number (0-255) or hex (#rrggbb).

display.showMemoryUsage is fully opt-in and only renders in expanded layout. It reports approximate system RAM usage from the local machine, not precise memory pressure inside Claude Code or a specific process. The number may overstate actual pressure because reclaimable OS cache and buffers can still be counted as used memory.

Usage Limits

Usage display is enabled by default when Claude Code provides subscriber rate_limits data on stdin. It shows your rate limit consumption on line 2 alongside the context bar.

Free/weekly-only accounts render the weekly window by itself instead of showing a ghost 5h: -- placeholder.

The 7-day percentage appears when above the display.sevenDayThreshold (default 80%):

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

To disable, set display.showUsage to false.

Requirements:

• Claude subscription usage data from Claude Code stdin
• Not available for API-key-only users

Troubleshooting: If usage doesn't appear:

• Ensure you're logged in with a Claude subscriber account (not API key)
• Check display.showUsage is not set to false in config
• API users see no usage display (they have pay-per-token, not rate limits)
• AWS Bedrock models display Bedrock and hide usage limits (usage is managed in AWS)
• Claude Code may leave rate_limits empty until after the first model response in a session
• Older Claude Code versions that do not emit rate_limits will not show subscriber usage

Example Configuration

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "memory", "environment", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showConfigCounts": true,
    "showDuration": true,
    "showMemoryUsage": true
  },
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "#FF6600"
  }
}

Display Examples

1 level (default): [Opus] │ my-project git:(main)

2 levels: [Opus] │ apps/my-project git:(main)

3 levels: [Opus] │ dev/apps/my-project git:(main)

With dirty indicator: [Opus] │ my-project git:(main*)

With ahead/behind: [Opus] │ my-project git:(main ↑2 ↓1)

With file stats: [Opus] │ my-project git:(main* !3 +1 ?2)

• ! = modified files, + = added/staged, ✘ = deleted, ? = untracked
• Counts of 0 are omitted for cleaner display

Troubleshooting

Config not applying?

• Check for JSON syntax errors: invalid JSON silently falls back to defaults
• Ensure valid values: pathLevels must be 1, 2, or 3; lineLayout must be expanded or compact
• Delete config and run /claude-hud:configure to regenerate

Git status missing?

• Verify you're in a git repository
• Check gitStatus.enabled is not false in config

Tool/agent/todo lines missing?

• These are hidden by default — enable with showTools, showAgents, showTodos in config
• They also only appear when there's activity to show

HUD not appearing after setup?

• Restart Claude Code so it picks up the new statusLine config
• On macOS, fully quit Claude Code and run claude again in your terminal

---

Requirements

• Claude Code v1.0.80+
• Node.js 18+ or Bun

---

Development

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

See CONTRIBUTING.md for guidelines.

---

License

MIT — see LICENSE

---

Star History