前言

用 Claude Code 跑長任務時，上下文余量、subagent 狀態(tài)、todo 進度常常對用戶不可見，工作流易因"盲飛"中斷。

本文介紹 Claude HUD 這款 statusline 插件（GitHub 26k Star，MIT 協(xié)議），通過 Claude Code 原生 statusline API + transcript JSONL 解析雙數(shù)據(jù)源，在輸入框下方常駐渲染上下文用量、工具活動、agent 狀態(tài)、todo 進度等狀態(tài)信息。

關鍵技術點包括：零運行時依賴、十余個 display 顯示開關、完整 colors 顏色體系、三預設即用、簡繁中文原生支持。適用于重度 Claude Code 用戶，尤其依賴 subagent 并行與長上下文任務的開發(fā)者。

Claude HUD 給 Claude Code 裝上實時狀態(tài)欄插件，告別上下文盲區(qū)

你正在用 Claude Code 改一個跨文件的 bug，它已經(jīng)連續(xù)跑了 20 分鐘。你不知道上下文還剩多少、不知道 subagent 在哪個目錄里翻代碼、不知道那 5 個 todo 完成了幾個–直到上下文突然耗盡、任務被打斷，你才意識到自己一直在"盲飛"。

Claude HUD 就是為這種盲飛時刻準備的：它在輸入框下方常駐一行狀態(tài)，把上下文用量、工具活動、agent 狀態(tài)、todo 進度實時攤在你眼前。

一、Claude Code 的"信息盲區(qū)"：從看不見到看得見

把 Claude Code 用得越久，你就越會感受到一種隱性的"信息稅"–它的能力很強，但過程中的關鍵狀態(tài)對你不可見。這種盲區(qū)具體表現(xiàn)為三類。

上下文余量未知。 Claude Code 的上下文窗口動輒 200K 甚至更大，但你看不到當前會話已經(jīng)吃了多少、還剩多少。等到它突然提示上下文不足、要求你 /compact 或開新會話時，前面的工作流往往已經(jīng)被打斷。長任務尤其痛：你無法在"快滿了"之前主動決策，只能被動響應。

subagent 行為黑盒。 當主 agent 派出 subagent 去探索代碼庫、跑測試或并行處理子任務時，這些子任務在你的視野里幾乎是靜默的–你不知道哪個 agent 還在跑、它停在哪一步、是否卡在某個目錄里反復讀同一個文件。任務越復雜，黑盒越深。

todo 進度不可見。 Claude Code 經(jīng)常自己列 todo 清單并逐項執(zhí)行，但這份清單藏在對話流里，你得往上翻才能看到還剩幾項沒做。20 分鐘的連續(xù)執(zhí)行中，進度感幾乎是零。

這三類盲區(qū)疊加起來，構成了 README 在 “What You See” 一節(jié)中要解決的完整問題域：Project path（當前所在項目）、Context health（上下文健康度）、Tool activity（工具活動）、Agent tracking（agent 跟蹤）、Todo progress（todo 進度）。Claude HUD 把這五項一次性補齊。

二、Claude HUD 是什么：一行狀態(tài)欄，一個 HUD

Claude HUD 是 Claude Code 的一個 statusline 插件，作者 Jarrod Watts。它在你輸入框下方常駐渲染一兩行（可擴展到更多行）狀態(tài)信息，覆蓋上下文用量、工具活動、agent 狀態(tài)、todo 進度等維度。整套東西本地運行，不聯(lián)網(wǎng)、不抓憑證，MIT 協(xié)議開源。

值得專門拎出來講的是迭代速度，覆蓋了 Bedrock/Vertex 成本顯示、繁體中文支持、model-scoped weekly usage、安全加固、CJK 進度條對齊修復等。這不是一個"發(fā)完就躺平"的項目，而是處于高速活躍期。

裝好之后，你看到的默認形態(tài)是這樣（來自 README）：

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

第一行告訴你"用的是什么模型、在哪個項目、git 分支是否臟"；第二行告訴你"上下文吃了多少、訂閱用量用了多少"。就這兩行，已經(jīng)把開篇那三個"不知道"補上了第一個。

三、它如何工作：原生 statusline API + transcript 解析

Claude HUD 的核心機制有兩條線，理解了它們，你就能解釋它的各種行為。

第一條線：走 Claude Code 原生 statusline API。 Claude Code 暴露了一個 statusline 擴展點–插件注冊一個可執(zhí)行入口，Claude Code 會周期性地把當前會話狀態(tài)以 JSON 形式通過 stdin 喂給這個入口，插件處理后把渲染好的字符串寫回 stdout，Claude Code 再把它繪制到輸入框下方。這意味著 Claude HUD 不需要 tmux、不需要單獨窗口、不需要你切屏，只要能跑 Claude Code 的終端就能用。

第二條線：雙數(shù)據(jù)源。 stdin 里的 JSON 只覆蓋一部分信息（模型名、上下文用量、transcript 路徑等），更動態(tài)的"工具調(diào)用、agent 狀態(tài)、todo 進度"來自 Claude Code 同時維護的 transcript JSONL 文件。Claude HUD 在拿到 transcript_path 后，會去解析這份 JSONL，提取出最近一次的 tool_use、subagent 調(diào)用、TodoWrite 等事件。數(shù)據(jù)流因此是這樣的：

Claude Code ──stdin JSON──> claude-hud ──stdout──> 終端
                                 │
                                 └──解析 transcript JSONL──> tools/agents/todos

源碼層面，src/ 目錄按職責切得很細：stdin.ts 負責讀 stdin，transcript.ts 解析 transcript JSONL，context-cache.ts 緩存上下文狀態(tài)，config.ts / config-reader.ts 管配置，再加上 cost.ts / effort.ts / git.ts / memory.ts / model-source.ts / speed-tracker.ts / auth.ts 等功能模塊，以及 i18n/、render/、utils/ 三個子目錄。入口是 dist/index.js（編譯產(chǎn)物，源碼 src/index.ts）。技術棧是 TypeScript + ESM + Node 18+，構建走 tsc。

執(zhí)行模式上，package.json 里的 test:stdin 腳本給出了很直白的證據(jù)–它就是一條管道：

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

你可以直接拿這條命令在本地驗證執(zhí)行模式：claude-hud 是"讀一次 stdin、輸出一次狀態(tài)行后退出"的單次進程，由 Claude Code 周期性調(diào)用。所以 README 里那句 “Updates every ~300ms”，根據(jù)項目文檔的描述，應當理解為 Claude Code 調(diào)用 statusline 的頻率，而不是 claude-hud 內(nèi)部跑了個 setInterval。

同理，README 宣稱的 “Native token data from Claude Code (not estimated)” 與 “scales with Claude Code’s reported context window size, including newer 1M-context sessions”，根據(jù)項目文檔，是指 token 數(shù)與窗口大小取自 Claude Code 經(jīng) stdin 報告的值，而非 claude-hud 本地估算–這兩項經(jīng)源碼核實與實現(xiàn)一致：token 數(shù)與上下文窗口大小均取自 stdin 的 context_window 字段，僅在舊版 Claude Code 未提供原生百分比時才回退到本地估算。

四、上手實戰(zhàn)：4 條命令裝好，3 個預設即用

Claude HUD 的上手成本被壓到了很低：4 條 slash 命令裝完，1 個交互式配置選預設，重啟即可見。

運行要求

• Claude Code v1.0.80+
• macOS / Linux：Node.js 18+ 或 Bun
• Windows：Node.js 18+

安裝 4 步

在 Claude Code 會話里依次執(zhí)行（命令來源：README “Install” 一節(jié)）：

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/reload-plugins
/claude-hud:setup

/claude-hud:setup 會幫你把 statusline 配置寫好。完成后重啟 Claude Code 讓新的 statusLine 配置生效，HUD 就會出現(xiàn)在輸入框下方。

三個預設即用

裝好后運行 /claude-hud:configure，在三個預設里選一個（定義來自 README）：

/claude-hud:configure 是引導式的，會帶你過布局、語言、常見顯示開關，支持保存前預覽–不用反復改了再看、看了再改。

平臺坑與解法

Linux 的 EXDEV 報錯。 /tmp 在大多數(shù) Linux 發(fā)行版上是 tmpfs，安裝時可能遇到 EXDEV: cross-device link not permitted。這是 Claude Code 平臺限制（issue #14799），不是 claude-hud 的 bug。解法是把臨時目錄指到一個真實文件系統(tǒng)上：

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

把這條放進你的 shell 啟動腳本或別名里，之后正常使用即可。

Windows 找不到 JavaScript 運行時。 如果 /claude-hud:setup 提示找不到 Node，說明你的 Windows 上還沒裝 Node.js。裝一份 LTS 就行：

winget install OpenJS.NodeJS.LTS

裝完重啟 shell（關掉當前終端、重開），讓 PATH 生效，然后重跑 /claude-hud:setup。

手動配置入口

如果引導式配置不夠用，各類高級選項都在配置文件里：

~/.claude/plugins/claude-hud/config.json

直接編輯這個 JSON 就能調(diào) colors.*、pathLevels、maxWidth、各類閾值、display.timeFormat、display.promptCacheTtlSeconds 等細粒度參數(shù)。改完保存，下一次 statusline 刷新即生效。

五、亮點與配置：從默認 2 行到深度定制

默認 2 行只是起點。Claude HUD 真正的差異化在于配置深度–你能精確控制每一行顯示什么、用什么顏色、中文還是英文。

可選顯示行

通過 /claude-hud:configure 打開后，默認隱藏的三行會被啟用（示例來自 README）：

? 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

這三行恰好分別對應開篇的三個"不知道"：工具在干什么、subagent 在哪、todo 進度幾成。? 表示進行中、? 表示完成、? 表示當前 todo 項。

display.* 顯示開關

顯示維度被拆成了十余個獨立開關，按需打開關閉（清單來自 README “Configuration”）：

• showTools / showSkills / showMcp：工具、技能、MCP 調(diào)用活動
• showAgents：subagent 狀態(tài)
• showTodos：todo 進度
• showCost：成本（含 Bedrock/Vertex）
• showDuration / showSpeed：會話時長、輸出速度
• showMemoryUsage：內(nèi)存占用
• showPromptCache：prompt cache 命中
• showAuth / showCompactions / showEffortLevel / showClaudeCodeVersion：認證方式、壓縮次數(shù)、推理努力等級、Claude Code 版本

這套開關的顆粒度足以讓重度用戶拼出自己舒適的信息密度，也讓 Essential / Minimal 預設能精確地"少顯示"。

colors.* 顏色體系

顏色不是寫死的。colors.* 下有 context、usage、warning、critical、model、project、git、gitBranch、label、custom 等鍵，每個都支持三種寫法（來自 README）：

• 顏色名（如 red）
• 256 色編號（如 196）
• hex（如 #ff5555）

你完全可以把上下文條調(diào)成跟終端主題一致的顏色，或者在 critical 閾值時用一個特別刺眼的紅色提醒自己。

布局、路徑、語言

• lineLayout：expanded（多行）或 compact（單行）。單行適合窄終端，多行適合看全信息。
• pathLevels：1-3，控制項目路徑顯示幾層目錄。
• language：en / zh / zh-Hans / zh-Hant / zh-TW。zh 是 zh-Hans 的別名，zh-TW 映射到 zh-Hant。簡繁中文都原生支持，對中文開發(fā)者很友好。

臨時禁用

調(diào)試時你想看原始 Claude Code 界面，不必卸載插件，設一個環(huán)境變量即可：

CLAUDE_HUD_DISABLE=1 claude

這一次會話不帶 HUD 啟動，下次正常啟動自動恢復。

六、邊界與注意事項：哪里能用，哪里要小心

Claude HUD 不是銀彈，它有幾條明確的邊界，用之前心里有數(shù)才能避開坑。

平臺兼容性。 前面提到的 Linux tmpfs EXDEV 和 Windows 找不到 Node 是兩個常見的安裝期問題，按第四節(jié)的解法處理即可。除此之外，macOS / Linux 用 Node 18+ 或 Bun 都行，Windows 只認 Node 18+（不支持 Bun），這是 README 明確寫的運行要求。

用量顯示的限制。 Context 條旁邊的 Usage 條不是人人都能看到，它依賴 Claude Code 在 stdin 里提供 subscriber rate_limits：

• API-key 用戶不可用：按 token 計費沒有 rate limits，Claude Code 不會提供這個字段，Usage 條自然也不出現(xiàn)。
• Bedrock 用戶：會顯示 Bedrock 標簽但隱藏用量限制，因為額度在 AWS 側管理。
• Claude Code 可能延遲提供：根據(jù)項目文檔，Claude Code 有時會在首條響應之后才把 rate_limits 喂進 stdin，所以會話剛開始那幾秒 Usage 條可能是空的，這不是 bug。
• 想補全或覆蓋官方用量數(shù)據(jù)，可以配置 externalUsagePath 指向一個本地用量快照文件作為補充或回退。

安全設計。 Claude HUD 的安全姿態(tài)是"本地、最小、可控"：

• 本地運行 by design：不發(fā)起網(wǎng)絡請求、不抓取憑證、不調(diào)用未公開的 Claude API。讀取范圍嚴格限定在 stdin 的 statusline JSON、Claude Code 提供的 transcript 路徑、~/.claude 下選定的配置文件、當前工作區(qū)的 git 元數(shù)據(jù)。
• 緩存文件寫在 ~/.claude/plugins/claude-hud，POSIX 下用私有權限，不會被其他用戶讀到。
• --extra-cmd 是高危選項：默認禁用，必須設環(huán)境變量 CLAUDE_HUD_ALLOW_EXTRA_CMD=1（或 true / yes / on）才會啟用。README 明確警告：這個選項等同任意代碼執(zhí)行，切勿使用不可信來源的命令。如果你不知道自己在干什么，就別碰它。

總結

回到開篇的"盲飛"–Claude HUD 把它變成了一種可選狀態(tài)，而不是默認狀態(tài)。它的價值是四件事的乘積：

1. 原生 statusline API 的零侵入：不搶窗口、不搶 tmux、不改你的工作流，絕大多數(shù)終端都能用。
2. 零運行時依賴的輕量：package.json 沒有 dependencies，裝上不會拖進一堆供應鏈包袱。
3. 配置深度的可塑性：十余個 display 開關、完整 colors 體系、布局/路徑/語言全可調(diào)，從 Minimal 到 Full 覆蓋大多數(shù)人的信息偏好。
4. 高速迭代的項目健康度：5 天 5 個版本，issue 響應快，CJK、Bedrock、繁體中文這些邊緣場景都在被照顧。

它尤其適合重度 Claude Code 用戶–尤其依賴 subagent 并行、經(jīng)常跑長上下文任務、需要主動管理 context window 的人。

對偶爾用一下的輕量用戶，默認 Minimal 預設也足夠了，快來給你的ClaudeCode也裝上吧。

到此這篇關于Claude HUD 如何給Claude Code裝上實時狀態(tài)欄插件的文章就介紹到這了,更多相關Claude Code 實時狀態(tài)欄插件內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章，希望大家以后多多支持腳本之家！

最新評論