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 и использует нативный API строки статуса Claude Code. Отдельное окно или терминальный мультиплексор не нужны.
Как установить и настроить?Внутри экземпляра Claude Code добавьте маркетплейс, установите плагин, а затем выполните /claude-hud:setup для настройки строки статуса. Она активируется после вашего следующего сообщения, перезапуск не нужен.
Нужно ли что-то кроме Claude Code, чтобы это работало?В Windows нужна среда выполнения JavaScript; для настройки поддерживается Node.js LTS. В Linux дополнительных зависимостей нет, но в старых версиях Claude Code может возникнуть проблема с файловой системой /tmp.
Есть ли подводные камни при установке, о которых стоит знать?Пользователи Linux на старых версиях Claude Code могут получить ошибку EXDEV, потому что /tmp — это отдельная файловая система tmpfs. Это исправлено в основном репозитории; в качестве обходного пути можно задать TMPDIR перед установкой. Пользователям Windows может понадобиться сначала установить среду выполнения Node.js, если установка не может найти JavaScript.
Какие пресеты доступны для макета 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