claude-hud README

The project's README from github.com/jarrodwatts/claude-hud. As one markdown file: 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 Stars

Claude HUD in action

🌐 English | 中文文档

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 if install fails with an EXDEV error

On older Claude Code versions, /tmp being a separate filesystem (tmpfs) caused plugin installation to fail with:

EXDEV: cross-device link not permitted

This Claude Code bug has since been fixed — if you hit it, update Claude Code first. If you can't update, set TMPDIR before installing:

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

Then run the install command below in that session.

/plugin install claude-hud

After that, reload plugins (no restart needed):

/reload-plugins
Prefer the terminal?

Steps 1–2 can also be done outside a session with the Claude Code CLI:

claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud

Then run /reload-plugins inside your session (or start a new one).

Step 3: Configure the statusline

/claude-hud:setup
⚠️ Windows users: Click here if setup says no JavaScript runtime was found

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

winget install OpenJS.NodeJS.LTS

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

Done! Claude Code reloads settings automatically — the HUD appears after your next message, no restart needed. If it doesn't show up, restart Claude Code (older versions require a restart to pick up statusLine changes).

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)

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:

Configuration

Customize your HUD anytime:

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

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, maxWidth, threshold overrides, display.timeFormat, display.hourCycle, and display.promptCacheTtlSeconds. Running /claude-hud:configure preserves those manual settings while still letting you change language, layout, and the common guided toggles.

If you run several Claude config directories via CLAUDE_CONFIG_DIR and symlink plugins/ to a shared location, plugins/claude-hud/config.json is the same physical file for all of them. Put per-directory settings in $CLAUDE_CONFIG_DIR/claude-hud.json instead - it uses the same shape, only needs the keys it changes, and is layered on top of the shared config at load time:

For example, put this in ~/.config/claude/work/claude-hud.json:

{ "display": { "customLine": "Work Team" } }

Simplified and Traditional Chinese HUD labels are available as explicit opt-ins. English stays the default unless you choose a Chinese locale in /claude-hud:configure or set language in config. The zh alias maps to Simplified Chinese, and zh-TW maps to Traditional Chinese. Guided config writes the canonical zh-Hans or zh-Hant value.

Options

Option Type Default Description
language en | zh | zh-Hans | zh-Hant | zh-TW en HUD label language. Use zh or zh-Hans for Simplified Chinese and zh-Hant or zh-TW for Traditional Chinese.
lineLayout string expanded Layout: expanded (multi-line) or compact (single line)
pathLevels 1-3 | full 1 Directory levels to show in project path, or full to show the entire absolute path
maxWidth number | null null Optional fallback width used only when terminal width detection fails completely
forceMaxWidth boolean false Always use maxWidth when it is set, even if terminal width detection returns a smaller value
elementOrder string[] ["project","addedDirs","context","usage","promptCache","memory","environment","tools","skills","mcp","agents","todos","sessionTime"] Expanded-mode element order. Omit entries to hide them in expanded mode. Existing configs keep their explicit order until updated.
projectLineOrder string[] [] Optional leading order of segments within the first line, in both layouts. Visibility stays with the display.show* flags, and omitted segments retain their existing renderer order. model covers provider + model + effort (plus the context bar in compact mode); project covers path + added dirs + git as one segment. Example: ["project","model"] puts the project/git block before the model badge.
display.mergeGroups string[][] [["context","usage"]] Expanded-mode groups that should share a line when adjacent. Set [] to disable merged lines.
display.rightAlign string[] [] Starts a right-aligned suffix at the first listed element in a merged row, preserving elementOrder and padding the gap with spaces. Requires the anchor to be in a display.mergeGroups group that actually renders on one line. Ignored when the terminal width is unknown, the anchor is first, or there is no room for padding. Example: ["context"] with a ["project","context","usage"] group keeps project/git left and pins context + usage right.
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
gitStatus.branchOverflow truncate | wrap truncate Keep current truncation behavior or let the git block wrap onto its own line boundary when possible
jjStatus.enabled boolean false Opt in to jj (Jujutsu) status. When enabled and a real .jj directory is found, jj is used instead of git for that repo — never both
jjStatus.showDirty boolean true Show * when the working-copy commit differs from its parent
jjStatus.showConflicts boolean true Show a !conflict marker when the working-copy commit has an unresolved conflict
display.showModel boolean true Show model name [Opus]
display.modelSource stdin | auto | transcript stdin Controls which source the model name comes from. stdin preserves the default behavior and always uses what Claude Code reports. auto opts into proxy redirect detection by using transcript models only for non-Claude models. transcript always uses the model from the API response. Transcript model values are terminal-sanitized and capped at 80 characters
display.showProvider boolean false Show the provider label before the model name, e.g. [Bedrock | Opus 4.6]. Useful when a custom proxy serves identically-named models from different providers. When off, an auto-detected provider still trails the model as before
display.providerName string "" Explicit provider label used with display.showProvider, e.g. for a custom proxy that can't be auto-detected. Falls back to the auto-detected provider (Bedrock/Vertex/MiniMax/Enterprise) when empty; capped at 40 chars
display.showAddedDirs boolean true Show extra workspace directories from /add-dir (e.g. +sparkle +lib-foo); empty array renders nothing. In both layouts at most 5 dirs render (overflow shown as +N more) and basenames are truncated to 24 chars with …
display.addedDirsLayout inline | line inline inline puts dirs next to the project name with a +name prefix per dir; line renders them on a separate Added dirs: name1, name2 line (no + prefix, comma-separated)
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.autoCompactWindow number | null null When set to a positive number such as 200000, compute the context percentage against this auto-compact window instead of the full model context window, matching the /context figure. Leave unset or null to preserve default full-window behavior.
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.showRoutedCost boolean false Also show cost for routed providers (Bedrock/Vertex), which showCost hides by default. Requires showCost too. Uses the native cost.total_cost_usd when positive (Cost), otherwise the token estimate (Est.)
display.showDailyCost boolean false Show today's cumulative spend across sessions as Today $12.34, accumulated from the native cost.total_cost_usd into a small per-day ledger in the plugin data directory. Resets at local midnight. Independent of showCost
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.usageValue percent | remaining percent Usage display format (25% used, or 75% remaining)
display.usageBarEnabled boolean true Display usage as visual bar instead of text
display.usageCompact boolean false Display usage in a shorter text form such as 5h: 25% (1h 30m); takes precedence over display.usageBarEnabled
display.showResetLabel boolean true Show the resets in prefix before usage countdowns
display.showModelScopedUsage boolean true Show the per-model weekly windows (model_scoped, e.g. Fable), whether they arrive on stdin or from the external usage snapshot. Set to false to render the usage line as if the payload carried none of them
display.timeFormat relative | absolute | both | elapsed | elapsedAndAbsolute relative How usage-window time is shown: countdown only (resets in 2h 30m), wall-clock reset (resets at 14:30), both, elapsed window percentage (53% elapsed), or elapsed plus wall-clock reset
display.hourCycle auto | h11 | h12 | h23 | h24 auto Hour cycle for wall-clock reset times (absolute/both/elapsedAndAbsolute modes). auto defers to the system locale; h23 forces 24-hour time (14:30) regardless of locale
display.showClockSeconds boolean false Show seconds in wall-clock reset times, e.g. at 14:30:07
display.sevenDayThreshold 0-100 80 Show 7-day usage when >= threshold (0 = always)
display.externalUsagePath string "" Optional absolute path to a local usage snapshot file. Relative paths are ignored. When stdin rate_limits are present, balance_label is appended and model_scoped windows fill in when stdin lacks them; when stdin windows are missing, valid usage windows can be used as a fallback
display.externalUsageWritePath string "" Optional absolute .json path in an existing directory. When stdin rate_limits exists, ClaudeHUD writes a private snapshot for other local tools. Relative paths, non-json files, and missing parent directories are ignored
display.externalUsageFreshnessMs number 300000 Maximum allowed age for the external usage snapshot before it is ignored
display.showTokenBreakdown boolean true Show token details at high context (85%+)
display.showTools boolean false Show tools activity line
display.showSkills boolean false Show active Skills detected from Skill tool invocations
display.showMcp boolean false Show active MCP servers detected from mcp__server__tool invocations
display.toolNameMaxLength number 0 Maximum displayed tool-name length. 0 keeps full names; MCP names may shorten to their final segment when truncating
display.toolsMaxVisible number 4 Maximum completed tools shown on the tools line. 0 means unlimited
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.showAuth boolean false Show the auth method (subscription plan) of the current login as its own segment at the end of the first line, e.g. Claude Max 20x. Derived from the oauthAccount block in {CLAUDE_CONFIG_DIR}.json; shows API Key when there is no OAuth login but ANTHROPIC_API_KEY is set
display.showAuthUser boolean false Show the logged-in account (email local part, falling back to profile display name) next to the auth method
display.authUserLength number 8 Maximum characters of the account name to display before truncating with …. 0 shows the full name
display.showAdvisor boolean false Inline the model configured via Claude Code's /advisor on the project line, e.g. Advisor: Opus 4.7. Read from the advisorModel field that Claude Code stamps on each assistant transcript record; sanitised and capped at 64 chars before rendering
display.advisorOverride string "" Optional manual override for the displayed advisor label. When non-empty, replaces transcript-driven detection. Also sanitised and capped at 64 chars
display.showSessionStartDate boolean false Show the transcript session start timestamp
display.showLastResponseAt boolean false Show how long ago the last assistant response was written
display.showCompactions boolean false Show how many context compactions (manual /compact or auto) have occurred this session, counted from transcript compact_boundary entries, e.g. Compactions: 2. Hidden until the first compaction
display.showEffortLevel boolean false Show the current reasoning effort in the model badge. Ultracode renders as ultracode(xhigh), detected from the session transcript so it tracks /effort changes made at runtime
display.effortFormat full | symbol | text full How the effort renders when display.showEffortLevel is on: symbol and level text (◑ high), symbol only (◑), or level text only (high). Ultracode keeps the full ◕ ultracode(xhigh) form under symbol so the marker is not lost, and levels without a known symbol fall back to the level text
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
display.showPromptCache boolean false Show the wall-clock time the session's prompt cache expires, read from the transcript
display.promptCacheTtlSeconds number 300 Compatibility fallback used only when the transcript has not reported a 5-minute or 1-hour cache tier
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

claude-hud (jarrodwatts/claude-hud)

Searching Database…

28.6K ·GitHub
Claude-hud
这是什么?Claude HUD 是一个 Claude Code 插件,它会在输入框下方始终显示一个实时状态栏,展示上下文用量、正在使用的工具、运行中的子代理以及待办任务的进度。
这是独立应用,还是运行在 Claude Code 内部?它是一个完全运行在 Claude Code 会话内部的插件,使用 Claude Code 原生的 statusline API,不需要单独的窗口或终端复用器。
我该如何安装和设置?在 Claude Code 实例中,先添加插件市场,再安装插件,然后运行 /claude-hud:setup 来配置状态栏。无需重启,在你发送下一条消息后即可生效。
运行它除了 Claude Code 还需要别的东西吗?在 Windows 上需要一个 JavaScript 运行时,设置时支持的是 Node.js LTS 版本。在 Linux 上没有额外依赖,但较旧版本的 Claude Code 可能会遇到 /tmp 文件系统问题。
安装时有哪些需要注意的坑?在较旧版本 Claude Code 的 Linux 上,可能会遇到 EXDEV 错误,原因是 /tmp 是独立的 tmpfs 文件系统。该问题已在上游修复;或者你可以在安装前设置 TMPDIR 作为临时解决办法。如果 Windows 上的设置找不到 JavaScript,可能需要先安装 Node.js 运行时。
HUD 布局有哪些预设?内置三种预设:Full(显示全部内容,包括工具、代理、待办、git、用量和耗时)、Essential(活动行加 git 状态)以及 Minimal(仅显示模型名称和上下文进度条)。
HUD 可以显示中文标签吗?可以。简体和繁体中文标签需要主动开启,可通过 /claude-hud:configure 设置,或设置 language 选项(zh/zh-Hans 为简体,zh-TW/zh-Hant 为繁体);默认是英文。
它能实时显示子代理和工具的活动吗?可以。它会解析会话记录,显示 Claude 正在使用哪些工具(读取/编辑/搜索)以及哪些子代理正在运行;每次交互后会重新渲染,并以 300 毫秒进行防抖处理。
我能查看会话费用和用量限制吗?可以。通过可选的显示开关,可以展示 Claude 订阅用户的用量限制、会话费用(优先使用 Claude Code 原生的费用数据,缺失时回退到本地估算),甚至还能显示跨会话的每日累计花费。
What are similar projects?claude-code, claude-ops, nodemon, evenfire, ordewell, craft-agents-oss, claudecodeui, ECC
Which topics is it in?statusline, node, observability, anthropic, monitoring, utility, plugin, claude, productivity, command-line-tool, claude-code, terminal
Creator
jarrodwatts
Size
3.5 MB
Stars
28.6K
Updated
CommitOct 18Releasev0.11.3Oct 17
Age
9mo
Commits · 90 Days