claude-hud

A Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress

27,338 stars JavaScript Markdown Skills API Spec #anthropic#claude#claude-code#cli
AI Prompts & Specs

Repository: jarrodwatts/claude-hud


Stars: 19769

CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

Claude HUD is a Claude Code plugin that displays a real-time multi-line statusline. It shows context health, tool activity, agent status, and todo progress.

Build Commands

bash
npm ci               # Install dependencies
npm run build        # Build TypeScript to dist/
Test with sample stdin data

echo '{"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000}}' | node dist/index.js

Architecture

Data Flow

text
Claude Code β†’ stdin JSON β†’ parse β†’ render lines β†’ stdout β†’ Claude Code displays
           β†˜ transcript_path β†’ parse JSONL β†’ tools/agents/todos

Key insight: The statusline is invoked every ~300ms by Claude Code. Each invocation:
1. Receives JSON via stdin (model, context, tokens - native accurate data)
2. Parses the transcript JSONL file for tools, agents, and todos
3. Renders multi-line output to stdout
4. Claude Code displays all lines

Data Sources

Native from stdin JSON (accurate, no estimation):
- model.display_name - Current model
- context_window.current_usage - Token counts
- context_window.context_window_size - Max context
- transcript_path - Path to session transcript

From transcript JSONL parsing:
- tool_use blocks β†’ tool name, input, start time
- tool_result blocks β†’ completion, duration
- Running tools = tool_use without matching tool_result
- TodoWrite calls β†’ todo list
- Task calls β†’ agent info

From config files:
- MCP count from ~/.claude/settings.json (mcpServers)
- Hooks count from ~/.claude/settings.json (hooks)
- Rules count from CLAUDE.md files

From Claude Code stdin rate limits:
- rate_limits.five_hour.used_percentage - 5-hour subscriber usage percentage
- rate_limits.five_hour.resets_at - 5-hour reset timestamp
- rate_limits.seven_day.used_percentage - 7-day subscriber usage percentage
- rate_limits.seven_day.resets_at - 7-day reset timestamp

File Structure

text
src/
β”œβ”€β”€ index.ts           # Entry point
β”œβ”€β”€ stdin.ts           # Parse Claude's JSON input
β”œβ”€β”€ transcript.ts      # Parse transcript JSONL
β”œβ”€β”€ config-reader.ts   # Read MCP/rules configs
β”œβ”€β”€ config.ts          # Load/validate user config
β”œβ”€β”€ git.ts             # Git status (branch, dirty, ahead/behind)
β”œβ”€β”€ types.ts           # TypeScript interfaces
└── render/
    β”œβ”€β”€ index.ts       # Main render coordinator
    β”œβ”€β”€ session-line.ts   # Compact mode: single line with all info
    β”œβ”€β”€ tools-line.ts     # Tool activity (opt-in)
    β”œβ”€β”€ agents-line.ts    # Agent status (opt-in)
    β”œβ”€β”€ todos-line.ts     # Todo progress (opt-in)
    β”œβ”€β”€ colors.ts         # ANSI color helpers
    └── lines/
        β”œβ”€β”€ index.ts      # Barrel export
        β”œβ”€β”€ project.ts    # Line 1: model bracket + project + git
        β”œβ”€β”€ identity.ts   # Line 2a: context bar
        β”œβ”€β”€ usage.ts      # Line 2b: usage bar (combined with identity)
        └── environment.ts # Config counts (opt-in)

Output Format (default expanded layout)

text
[Opus] β”‚ my-project git:(main*)
Context β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘ 45% β”‚ Usage β–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 25% (1h 30m / 5h)

Lines 1-2 always shown. Additional lines are opt-in via config:
- Tools line (showTools): ◐ Edit: auth.ts | βœ“ Read Γ—3
- Agents line (showAgents): ◐ explore [haiku]: Finding auth code
- Todos line (showTodos): β–Έ Fix authentication bug (2/5)
- Environment line (showConfigCounts): 2 CLAUDE.md | 4 rules

Context Thresholds

| Threshold | Color | Action |
|-----------|-------|--------|
| <70% | Green | Normal |
| 70-85% | Yellow | Warning |
| >85% | Red | Show token breakdown |

Plugin Configuration

The plugin manifest is in .claude-plugin/plugin.json (metadata only - name, description, version, author).

StatusLine configuration must be added to the user's ~/.claude/settings.json via /claude-hud:setup.

The setup command adds an auto-updating command that finds the latest installed version at runtime.

Note: statusLine is NOT a valid plugin.json field. It must be configured in settings.json after plugin installation. Updates are automatic - no need to re-run setup.

Dependencies

- Runtime: Node.js 18+ or Bun
- Build: TypeScript 5, ES2022 target, NodeNext modules


README.md

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.

![License](LICENSE)
![Stars](https://github.com/jarrodwatts/claude-hud/stargazers)

!Claude HUD in action

Install

Inside a Claude Code instance, run the following commands:

Step 1: Add the marketplace

text
/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the plugin

<details>
<summary><strong>⚠️ Linux users: Click here first</strong></summary>

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

text
EXDEV: cross-device link not permitted

Fix: Set TMPDIR before installing:

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

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

</details>

text
/plugin install claude-hud

After that, reload plugins:

text
/reload-plugins


Step 3: Configure the statusline

text
/claude-hud:setup

<details>
<summary><strong>⚠️ Windows users: Click here if setup says no JavaScript runtime was found</strong></summary>

On Windows, Node.js LTS is the recommended runtime for Claude HUD. If setup says no JavaScript runtime was found, install Node.js for your shell first:

powershell
winget install OpenJS.NodeJS.LTS

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

</details>

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)


text
[Opus] β”‚ my-project git:(main*)
Context β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘ 45% β”‚ Usage β–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 25% (1h 30m / 5h)

- Line 1 β€” Model, provider label when positively identified (for example Bedrock), project path, git branch
- Line 2 β€” Context bar (green β†’ yellow β†’ red) and usage rate limits

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


text
◐ 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.

text
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:

text
/claude-hud:configure

The guided flow handles layout, language, and common 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), pick a label language, then fine-tune individual elements
- Customize anytime: Toggle items on/off, adjust git display style, switch layouts, or change label language
- 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 while still letting you change language, layout, and the common guided toggles.

Chinese HUD labels are available as an explicit opt-in. English stays the default unless you choose δΈ­ζ–‡ in /claude-hud:configure or set language in config.

Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| language | en \| zh | en | HUD label language. English is the default; set zh to enable Chinese labels. |
| 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.pushWarningThreshold | number | 0 | Color the ahead count with the warning color at or above this unpushed-commit count (0 disables it) |
| gitStatus.pushCriticalThreshold | number | 0 | Color the ahead count with the critical color at or above this unpushed-commit count (0 disables it) |
| 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.showCost | boolean | false | Show session cost using Claude Code's native cost.total_cost_usd when available, with a local estimate fallback for direct Anthropic sessions |
| display.showOutputStyle | boolean | false | Show the active Claude Code outputStyle from settings files as style: <name> |
| 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.

display.showCost is fully opt-in. ClaudeHUD prefers the native cost.total_cost_usd field that Claude Code provides on stdin when it is available. If that field is absent or invalid for a direct Anthropic session, ClaudeHUD falls back to the existing local transcript-based estimate so the cost line still works on older payloads. The native field is absent before the first API response in a session, so the cost display may stay hidden until then. ClaudeHUD also keeps the cost hidden for known routed providers such as Bedrock, because cloud-provider billed sessions may report $0.00 or omit the field even though the session was not literally free.

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.

ClaudeHUD intentionally trusts only the official statusline stdin payload for live usage. It does not read local OAuth credentials or poll undocumented usage endpoints in the background.

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%):

text
Context β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘ 45% β”‚ Usage β–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 25% (1h 30m / 5h) | β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ 85% (2d / 7d)

To disable, set display.showUsage to false.

Requirements:
- Claude Code must include subscriber rate_limits data on stdin for the current session
- 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
- Some Claude Code builds and subscription tiers may still omit rate_limits, even after the first response
- When rate_limits is missing, ClaudeHUD will hide usage instead of falling back to credential scraping or undocumented API calls

Example Configuration

json
{
  "language": "zh",
  "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

bash
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

![Star History Chart](https://star-history.com/#jarrodwatts/claude-hud&Date)