{"slug": "claude-code-plugin-that-shows-what-s-happening", "title": "Claude Code plugin that shows what's happening", "summary": "A new Claude Code plugin called Claude HUD provides real-time visibility into context usage, active tools, running agents, and task progress directly within the terminal. The plugin installs via Claude Code's marketplace and uses the platform's native statusline API to display project path, context health, tool activity, agent tracking, and todo progress without requiring separate windows or tmux. Users can customize the display with Full, Essential, or Minimal presets and configure layout, language, and individual elements through a guided setup or direct config file editing.", "body_md": "A Claude Code plugin that shows what's happening — context usage, active tools, running agents, and todo progress. Always visible below your input.\n\n🌐 English |\n\n[中文文档]\n\nInside a Claude Code instance, run the following commands:\n\n**Step 1: Add the marketplace**\n\n```\n/plugin marketplace add jarrodwatts/claude-hud\n```\n\n**Step 2: Install the plugin**\n\n⚠️ Linux users: Click here first\n\nOn Linux, `/tmp`\n\nis often a separate filesystem (tmpfs), which causes plugin installation to fail with:\n\n```\nEXDEV: cross-device link not permitted\n```\n\n**Fix**: Set TMPDIR before installing:\n\n```\nmkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude\n```\n\nThen run the install command below in that session. This is a [Claude Code platform limitation](https://github.com/anthropics/claude-code/issues/14799).\n\n```\n/plugin install claude-hud\n```\n\nAfter that, reload plugins:\n\n```\n/reload-plugins\n```\n\n**Step 3: Configure the statusline**\n\n```\n/claude-hud:setup\n```\n\n⚠️ Windows users: Click here if setup says no JavaScript runtime was found\n\nOn 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:\n\n```\nwinget install OpenJS.NodeJS.LTS\n```\n\nThen restart your shell and run `/claude-hud:setup`\n\nagain.\n\nDone! Restart Claude Code to load the new statusLine config, then the HUD will appear.\n\nOn Windows, make that a full Claude Code restart after setup writes the new `statusLine`\n\nconfig.\n\nClaude HUD gives you better insights into what's happening in your Claude Code session.\n\n| What You See | Why It Matters |\n|---|---|\nProject path |\nKnow which project you're in (configurable 1-3 directory levels) |\nContext health |\nKnow exactly how full your context window is before it's too late |\nTool activity |\nWatch Claude read, edit, and search files as it happens |\nAgent tracking |\nSee which subagents are running and what they're doing |\nTodo progress |\nTrack task completion in real-time |\n\n```\n[Opus] │ my-project git:(main*)\nContext █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)\n```\n\n**Line 1**— Model, provider label when positively identified (for example`Bedrock`\n\n,`Vertex`\n\n), project path, git branch**Line 2**— Context bar (green → yellow → red) and usage rate limits\n\n```\n◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← Tools activity\n◐ explore [haiku]: Finding auth code (2m 15s)    ← Agent status\n▸ Fix authentication bug (2/5)                   ← Todo progress\n```\n\nClaude HUD uses Claude Code's native **statusline API** — no separate window, no tmux required, works in any terminal.\n\n```\nClaude Code → stdin JSON → claude-hud → stdout → displayed in your terminal\n           ↘ transcript JSONL (tools, agents, todos)\n```\n\n**Key features:**\n\n- Native token data from Claude Code (not estimated)\n- Scales with Claude Code's reported context window size, including newer 1M-context sessions\n- Parses the transcript for tool/agent activity\n- Updates every ~300ms\n\nCustomize your HUD anytime:\n\n```\n/claude-hud:configure\n```\n\nThe 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:\n\n**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\n\n| Preset | What's Shown |\n|---|---|\nFull |\nEverything enabled — tools, agents, todos, git, usage, duration |\nEssential |\nActivity lines + git status, minimal info clutter |\nMinimal |\nCore only — just model name and context bar |\n\nAfter choosing a preset, you can turn individual elements on or off.\n\nEdit `~/.claude/plugins/claude-hud/config.json`\n\ndirectly for advanced settings such as `colors.*`\n\n,\n`pathLevels`\n\n, `maxWidth`\n\n, threshold overrides, `display.timeFormat`\n\n, and `display.promptCacheTtlSeconds`\n\n. Running `/claude-hud:configure`\n\npreserves those manual settings while still letting you change `language`\n\n, layout, and the common\nguided toggles.\n\nChinese HUD labels are available as an explicit opt-in. English stays the default unless you choose `中文`\n\nin `/claude-hud:configure`\n\nor set `language`\n\nin config. The short `zh`\n\nalias remains valid, and new guided config writes the canonical `zh-Hans`\n\nvalue.\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n`language` |\n`en` | `zh` | `zh-Hans` |\n`en` |\nHUD label language. English is the default; set `zh` or `zh-Hans` to enable Simplified Chinese labels. |\n`lineLayout` |\nstring | `expanded` |\nLayout: `expanded` (multi-line) or `compact` (single line) |\n`pathLevels` |\n1-3 | 1 | Directory levels to show in project path |\n`maxWidth` |\nnumber | `null` |\n`null` |\nOptional fallback width used only when terminal width detection fails completely |\n`forceMaxWidth` |\nboolean | false | Always use `maxWidth` when it is set, even if terminal width detection returns a smaller value |\n`elementOrder` |\nstring[] | `[\"project\",\"context\",\"usage\",\"promptCache\",\"memory\",\"environment\",\"tools\",\"agents\",\"todos\",\"sessionTime\"]` |\nExpanded-mode element order. Omit entries to hide them in expanded mode. Existing configs keep their explicit order until updated. |\n`display.mergeGroups` |\nstring[][] | `[[\"context\",\"usage\"]]` |\nExpanded-mode groups that should share a line when adjacent. Set `[]` to disable merged lines. |\n`gitStatus.enabled` |\nboolean | true | Show git branch in HUD |\n`gitStatus.showDirty` |\nboolean | true | Show `*` for uncommitted changes |\n`gitStatus.showAheadBehind` |\nboolean | false | Show `↑N ↓N` for ahead/behind remote |\n`gitStatus.pushWarningThreshold` |\nnumber | 0 | Color the ahead count with the warning color at or above this unpushed-commit count (`0` disables it) |\n`gitStatus.pushCriticalThreshold` |\nnumber | 0 | Color the ahead count with the critical color at or above this unpushed-commit count (`0` disables it) |\n`gitStatus.showFileStats` |\nboolean | false | Show file change counts `!M +A ✘D ?U` |\n`gitStatus.branchOverflow` |\n`truncate` | `wrap` |\n`truncate` |\nKeep current truncation behavior or let the git block wrap onto its own line boundary when possible |\n`display.showModel` |\nboolean | true | Show model name `[Opus]` |\n`display.showAddedDirs` |\nboolean | 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 `…` |\n`display.addedDirsLayout` |\n`inline` | `line` |\n`inline` |\n`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) |\n`display.showContextBar` |\nboolean | true | Show visual context bar `████░░░░░░` |\n`display.contextValue` |\n`percent` | `tokens` | `remaining` | `both` |\n`percent` |\nContext display format (`45%` , `45k/200k` , `55%` remaining, or `45% (45k/200k)` ) |\n`display.showConfigCounts` |\nboolean | false | Show CLAUDE.md, rules, MCPs, hooks counts |\n`display.showCost` |\nboolean | false | Show session cost using Claude Code's native `cost.total_cost_usd` when available, with a local estimate fallback for direct Anthropic sessions |\n`display.showOutputStyle` |\nboolean | false | Show the active Claude Code `outputStyle` from settings files as `style: <name>` |\n`display.showDuration` |\nboolean | false | Show session duration `⏱️ 5m` |\n`display.showSpeed` |\nboolean | false | Show output token speed `out: 42.1 tok/s` |\n`display.showUsage` |\nboolean | true | Show Claude subscriber usage limits when available |\n`display.usageValue` |\n`percent` | `remaining` |\n`percent` |\nUsage display format (`25%` used, or `75%` remaining) |\n`display.usageBarEnabled` |\nboolean | true | Display usage as visual bar instead of text |\n`display.usageCompact` |\nboolean | false | Display usage in a shorter text form such as `5h: 25% (1h 30m)` ; takes precedence over `display.usageBarEnabled` |\n`display.showResetLabel` |\nboolean | true | Show the `resets in` prefix before usage countdowns |\n`display.timeFormat` |\n`relative` | `absolute` | `both` | `elapsed` | `elapsedAndAbsolute` |\n`relative` |\nHow 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 |\n`display.sevenDayThreshold` |\n0-100 | 80 | Show 7-day usage when >= threshold (0 = always) |\n`display.externalUsagePath` |\nstring | `\"\"` |\nOptional path to a local usage snapshot file used only when stdin `rate_limits` are missing |\n`display.externalUsageWritePath` |\nstring | `\"\"` |\nOptional 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 |\n`display.externalUsageFreshnessMs` |\nnumber | `300000` |\nMaximum allowed age for the external usage snapshot before it is ignored |\n`display.showTokenBreakdown` |\nboolean | true | Show token details at high context (85%+) |\n`display.showTools` |\nboolean | false | Show tools activity line |\n`display.toolNameMaxLength` |\nnumber | `0` |\nMaximum displayed tool-name length. `0` keeps full names; MCP names may shorten to their final segment when truncating |\n`display.toolsMaxVisible` |\nnumber | `4` |\nMaximum completed tools shown on the tools line. `0` means unlimited |\n`display.showAgents` |\nboolean | false | Show agents activity line |\n`display.showTodos` |\nboolean | false | Show todos progress line |\n`display.showSessionName` |\nboolean | false | Show session slug or custom title from `/rename` |\n`display.showSessionStartDate` |\nboolean | false | Show the transcript session start timestamp |\n`display.showLastResponseAt` |\nboolean | false | Show how long ago the last assistant response was written |\n`display.showClaudeCodeVersion` |\nboolean | false | Show the installed Claude Code version, e.g. `CC v2.1.81` |\n`display.showMemoryUsage` |\nboolean | false | Show an approximate system RAM usage line in expanded layout |\n`display.showPromptCache` |\nboolean | false | Show a prompt cache countdown based on the last assistant response timestamp in the transcript |\n`display.promptCacheTtlSeconds` |\nnumber | `300` |\nPrompt cache TTL in seconds. Keep the default for Pro, set `3600` for Max |\n`colors.context` |\ncolor value | `green` |\nBase color for the context bar and context percentage |\n`colors.usage` |\ncolor value | `brightBlue` |\nBase color for usage bars and percentages below warning thresholds |\n`colors.warning` |\ncolor value | `yellow` |\nWarning color for context thresholds and usage warning text |\n`colors.usageWarning` |\ncolor value | `brightMagenta` |\nWarning color for usage bars and percentages near their threshold |\n`colors.critical` |\ncolor value | `red` |\nCritical color for limit-reached states and critical thresholds |\n`colors.model` |\ncolor value | `cyan` |\nColor for the model badge such as `[Opus]` |\n`colors.project` |\ncolor value | `yellow` |\nColor for the project path |\n`colors.git` |\ncolor value | `magenta` |\nColor for git wrapper text such as `git:(` and `)` |\n`colors.gitBranch` |\ncolor value | `cyan` |\nColor for the git branch and branch status text |\n`colors.label` |\ncolor value | `dim` |\nColor for labels and secondary metadata such as `Context` , `Usage` , counts, and progress text |\n`colors.custom` |\ncolor value | `208` |\nColor for the optional custom line |\n`colors.barFilled` |\nstring | `█` |\nCharacter used for the filled portion of progress bars |\n`colors.barEmpty` |\nstring | `░` |\nCharacter used for the empty portion of progress bars |\n\n`colors.barFilled`\n\nand `colors.barEmpty`\n\naccept a single visible grapheme. Control characters, invisible format characters (bidi controls, zero-width joiners, variation selectors), line/paragraph separators, and noncharacters are rejected. Wide characters (emoji, CJK) may affect bar alignment depending on the terminal.\n\nSupported color names: `dim`\n\n, `red`\n\n, `green`\n\n, `yellow`\n\n, `magenta`\n\n, `cyan`\n\n, `brightBlue`\n\n, `brightMagenta`\n\n. You can also use a 256-color number (`0-255`\n\n) or hex (`#rrggbb`\n\n).\n\n`display.showMemoryUsage`\n\nis fully opt-in and only renders in `expanded`\n\nlayout. 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.\n\n`display.showCost`\n\nis fully opt-in. ClaudeHUD prefers the native `cost.total_cost_usd`\n\nfield 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 and Vertex AI, because cloud-provider billed sessions may report `$0.00`\n\nor omit the field even though the session was not literally free.\n\n`display.showPromptCache`\n\nis fully opt-in. When enabled, ClaudeHUD looks at the timestamp of the last assistant response in the local transcript and shows a live countdown until the prompt cache expires. The default TTL is 5 minutes (`300`\n\nseconds). Set `display.promptCacheTtlSeconds`\n\nto `3600`\n\nif you want a 1-hour Max-style window. If the transcript does not have an assistant timestamp yet, the cache element stays hidden.\n\nUsage display is **enabled by default** when Claude Code provides subscriber `rate_limits`\n\ndata on stdin. It shows your rate limit consumption on line 2 alongside the context bar.\n\nSet `display.usageValue`\n\nto `remaining`\n\nto show quota left instead of quota used. Warning colors and 7-day threshold checks still use the underlying used percentage.\n\nClaudeHUD prefers the official statusline stdin payload. If `rate_limits`\n\nare missing, you can opt into a local sidecar fallback by setting `display.externalUsagePath`\n\nto a JSON snapshot written by another tool such as a proxy. Stdin still wins whenever both sources exist.\n\nThe fallback snapshot must be fresh enough (`display.externalUsageFreshnessMs`\n\n) and include valid `updated_at`\n\n, plus a `five_hour`\n\nwindow, `seven_day`\n\nwindow, or `balance_label`\n\n. `balance_label`\n\nis optional text for prepaid provider balances; it is trimmed, length-limited, and sanitized before display. Invalid JSON, stale files, or invalid timestamps are ignored quietly.\n\nSet `display.externalUsageWritePath`\n\nif you want ClaudeHUD to write the official stdin `rate_limits`\n\ninto a local snapshot for other tools. The path must be absolute, end in `.json`\n\n, and live in an existing directory. ClaudeHUD writes the file with private permissions and ignores invalid paths quietly.\n\nFree/weekly-only accounts render the weekly window by itself instead of showing a ghost `5h: --`\n\nplaceholder.\n\nThe 7-day percentage appears when above the `display.sevenDayThreshold`\n\n(default 80%):\n\n```\nContext █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)\n```\n\nTo disable, set `display.showUsage`\n\nto `false`\n\n.\n\nReset times use relative countdowns by default. Set `display.timeFormat`\n\nto `absolute`\n\nfor wall-clock\ntimes, `both`\n\nto show both forms, `elapsed`\n\nto show how far through each usage window you are, or\n`elapsedAndAbsolute`\n\nto show elapsed window progress plus the wall-clock reset time. This setting is\nmanual-only today; `/claude-hud:configure`\n\npreserves it without editing it.\n\nSet `display.showResetLabel`\n\nto `false`\n\nif you want shorter usage countdowns such as `(3h 17m)`\n\ninstead of `(resets in 3h 17m)`\n\n.\n\nSet `display.usageCompact`\n\nto `true`\n\nif you want the shorter usage-only form, for example `5h: 25% (1h 30m)`\n\n. Compact usage takes precedence over `display.usageBarEnabled`\n\n.\n\n**Requirements:**\n\n- Claude Code must include subscriber\n`rate_limits`\n\ndata on stdin for the current session - Not available for API-key-only users\n\n**Troubleshooting:** If usage doesn't appear:\n\n- Ensure you're logged in with a Claude subscriber account (not API key)\n- Check\n`display.showUsage`\n\nis not set to`false`\n\nin config - API users see no usage display (they have pay-per-token, not rate limits)\n- AWS Bedrock models display\n`Bedrock`\n\nand hide usage limits (usage is managed in AWS) - Google Vertex AI models display\n`Vertex`\n\nand hide cost estimates (pricing differs from Anthropic direct) - Claude Code may leave\n`rate_limits`\n\nempty until after the first model response in a session - Some Claude Code builds and subscription tiers may still omit\n`rate_limits`\n\n, even after the first response - If you configured\n`display.externalUsagePath`\n\n, ClaudeHUD will try that local snapshot before hiding usage - ClaudeHUD never falls back to credential scraping or undocumented API calls\n\nExample fallback snapshot:\n\n```\n{\n  \"updated_at\": \"2026-04-20T12:00:00.000Z\",\n  \"five_hour\": {\n    \"used_percentage\": 42,\n    \"resets_at\": \"2026-04-20T15:00:00.000Z\"\n  },\n  \"seven_day\": {\n    \"used_percentage\": 84,\n    \"resets_at\": \"2026-04-27T12:00:00.000Z\"\n  }\n}\n{\n  \"language\": \"zh\",\n  \"lineLayout\": \"expanded\",\n  \"pathLevels\": 2,\n  \"elementOrder\": [\"project\", \"tools\", \"context\", \"usage\", \"memory\", \"environment\", \"agents\", \"todos\", \"sessionTime\"],\n  \"gitStatus\": {\n    \"enabled\": true,\n    \"showDirty\": true,\n    \"showAheadBehind\": true,\n    \"showFileStats\": true\n  },\n  \"display\": {\n    \"showTools\": true,\n    \"showAgents\": true,\n    \"showTodos\": true,\n    \"showConfigCounts\": true,\n    \"showDuration\": true,\n    \"showMemoryUsage\": true\n  },\n  \"colors\": {\n    \"context\": \"cyan\",\n    \"usage\": \"cyan\",\n    \"warning\": \"yellow\",\n    \"usageWarning\": \"magenta\",\n    \"critical\": \"red\",\n    \"model\": \"cyan\",\n    \"project\": \"yellow\",\n    \"git\": \"magenta\",\n    \"gitBranch\": \"cyan\",\n    \"label\": \"dim\",\n    \"custom\": \"#FF6600\"\n  }\n}\n```\n\n**1 level (default):** `[Opus] │ my-project git:(main)`\n\n**2 levels:** `[Opus] │ apps/my-project git:(main)`\n\n**3 levels:** `[Opus] │ dev/apps/my-project git:(main)`\n\n**With dirty indicator:** `[Opus] │ my-project git:(main*)`\n\n**With ahead/behind:** `[Opus] │ my-project git:(main ↑2 ↓1)`\n\n**With file stats:** `[Opus] │ my-project git:(main* !3 +1 ?2)`\n\n`!`\n\n= modified files,`+`\n\n= added/staged,`✘`\n\n= deleted,`?`\n\n= untracked- Counts of 0 are omitted for cleaner display\n\n**Config not applying?**\n\n- Check for JSON syntax errors: invalid JSON silently falls back to defaults\n- Ensure valid values:\n`pathLevels`\n\nmust be 1, 2, or 3;`lineLayout`\n\nmust be`expanded`\n\nor`compact`\n\n;`maxWidth`\n\nmust be a positive number - Delete config and run\n`/claude-hud:configure`\n\nto regenerate\n\n**Git status missing?**\n\n- Verify you're in a git repository\n- Check\n`gitStatus.enabled`\n\nis not`false`\n\nin config\n\n**Tool/agent/todo lines missing?**\n\n- These are hidden by default — enable with\n`showTools`\n\n,`showAgents`\n\n,`showTodos`\n\nin config - They also only appear when there's activity to show\n\n**HUD not appearing after setup?**\n\n- Restart Claude Code so it picks up the new statusLine config\n- On macOS, fully quit Claude Code and run\n`claude`\n\nagain in your terminal\n\n- Claude Code v1.0.80+\n- macOS/Linux: Node.js 18+ or Bun\n- Windows: Node.js 18+\n\n```\ngit clone https://github.com/jarrodwatts/claude-hud\ncd claude-hud\nnpm ci && npm run build\nnpm test\n```\n\nSee [CONTRIBUTING.md](/jarrodwatts/claude-hud/blob/main/CONTRIBUTING.md) for guidelines.\n\nMIT — see [LICENSE](/jarrodwatts/claude-hud/blob/main/LICENSE)", "url": "https://wpnews.pro/news/claude-code-plugin-that-shows-what-s-happening", "canonical_source": "https://github.com/jarrodwatts/claude-hud", "published_at": "2026-05-31 10:22:18+00:00", "updated_at": "2026-05-31 10:47:30.077870+00:00", "lang": "en", "topics": ["ai-tools", "ai-products", "ai-agents", "ai-infrastructure"], "entities": ["Claude Code", "Claude HUD", "jarrodwatts/claude-hud", "Anthropic", "Node.js", "OpenJS.NodeJS.LTS", "Linux", "Windows"], "alternates": {"html": "https://wpnews.pro/news/claude-code-plugin-that-shows-what-s-happening", "markdown": "https://wpnews.pro/news/claude-code-plugin-that-shows-what-s-happening.md", "text": "https://wpnews.pro/news/claude-code-plugin-that-shows-what-s-happening.txt", "jsonld": "https://wpnews.pro/news/claude-code-plugin-that-shows-what-s-happening.jsonld"}}