摘要本文介紹一個(gè)Claude Code 自定義狀態(tài)欄工具 claude-code-statusline并帶你完成安裝與 Claude Code 接入配置顯示模型、Git、上下文、token 和任務(wù)用時(shí)等并通過終端界面或 CLI 配置主狀態(tài)欄、子 Agent 行及可選實(shí)時(shí)指標(biāo)。一、為什么給 Claude Code 加一個(gè)狀態(tài)欄用 Claude Code 做任務(wù)時(shí)除了看回復(fù)內(nèi)容我們還會(huì)關(guān)心當(dāng)前使用什么模型、正在操作哪個(gè)目錄、Git 工作區(qū)有沒有變化、上下文還剩多少以及這次任務(wù)已經(jīng)運(yùn)行了多久。claude-code-statusline這個(gè)工具把這些信息集中到會(huì)話底部并提供可配置的子 Agent 狀態(tài)行。主欄支持 60 個(gè)顯示項(xiàng)子 Agent 行支持 14 個(gè)顯示項(xiàng)可以按自己的工作習(xí)慣選擇和排序。剛開始使用時(shí)保留模型、目錄、Git、上下文余量和任務(wù)用時(shí)就夠了。下面從安裝開始逐步配出一套日?？捎玫慕缑妗６?、準(zhǔn)備環(huán)境完成安裝與接入2026.10.18 更新TypeScript 重構(gòu)與 npm 安裝倉庫已使用TypeScript 重構(gòu)原 Python 實(shí)現(xiàn)。從v3.0.0開始軟件包通過 npm 分發(fā)后續(xù)新版不再支持通過 pipx 安裝或更新Python/pipx 方式保留用于歷史版本。工具版本安裝與更新方式軟件包名v2.0.0 及之前Python pipxpipx 支持的最后一個(gè)版本為 v2.0.0fbincon-claude-code-statuslinev3.0.0 及之后Node.js npmnpm 分發(fā)的首個(gè)正式版本為 v3.0.0fbincon/claude-code-statusline已有 pipx 安裝的用戶請(qǐng)先閱讀第七節(jié)新增的“從 Python/pipx 遷移到 npm”再切換安裝方式。1. 準(zhǔn)備新版運(yùn)行環(huán)境平臺(tái)運(yùn)行環(huán)境Linux / WSLNode.js 22.x 或 24.xx64Windows 10/11Node.js 22.x 或 24.xx64macOS 14Node.js 22.x 或 24.xIntel / Apple SiliconWindows ARM 設(shè)備使用 x64 Node 仿真原生 Windows ARM64 和 32 位運(yùn)行時(shí)暫不在支持范圍。WSL 用戶在 WSL 內(nèi)安裝并使用同一環(huán)境中的 Claude Code。先準(zhǔn)備 Node.js、npm 和 Claude Code CLI在終端檢查node --version npm --version claude --version要顯示 Git 信息還需讓git --version正常運(yùn)行。新版 npm 包已包含受支持平臺(tái)的原生依賴正常安裝和運(yùn)行無需 Python、pipx 或編譯器。2. 安裝 npm 軟件包首次安裝新版在 Bash、Zsh 或 PowerShell 中執(zhí)行npm install --global --ignore-scripts fbincon/claude-code-statusline安裝后確保 npm 的全局命令目錄位于 PATH 中調(diào)整 PATH 后重新打開終端。運(yùn)行命令仍為claude-statusline。Windows 的 npm 入口使用claude-statusline.cmd本節(jié)新增步驟及后文通用配置命令均按此替換原文中的claude-statusline.exe對(duì)應(yīng)歷史 Python/pipx 安裝。3. 將新版接入 Claude Code在終端依次執(zhí)行Windows 將命令名替換為claude-statusline.cmdclaude-statusline --version claude-statusline install --dry-run claude-statusline install claude-statusline doctor--version確認(rèn)實(shí)際運(yùn)行的是新版install --dry-run預(yù)覽接入改動(dòng)install寫入本工具的 Claude Code 接入doctor檢查環(huán)境與接入狀態(tài)。npm 安裝軟件包后還需要執(zhí)行接入步驟。檢查通過后在受信任終端重啟 Claude Code加載狀態(tài)欄、命令和插件。兼容宿主上的兩個(gè)編輯器入口默認(rèn)啟用保留已有明確關(guān)閉偏好原生計(jì)時(shí)與高級(jí)實(shí)時(shí)采集的新安裝默認(rèn)值見第六節(jié)更新。若遇到已有狀態(tài)欄或同名入口沖突按新版沖突處理說明檢查歸屬后處理。以下保留原 Python/pipx 安裝與接入內(nèi)容適用于 v2.0.0 及之前。如需明確安裝最后一個(gè) Python 版可執(zhí)行pipx install fbincon-claude-code-statusline2.0.0這一路徑不會(huì)安裝 npm 新版。1. 檢查前置環(huán)境平臺(tái)Python 環(huán)境Linux / WSLPython 3.10Windows 10/11CPython 3.10–3.14x86/x64自動(dòng)安裝 windows-curses 依賴macOS 14提供 curses 的 CPython 3.10–3.14Intel / Apple SiliconWindows ARM 設(shè)備可使用 x64 Python 仿真原生 ARM64 Python 暫不在支持范圍。WSL 用戶在 WSL 內(nèi)完成安裝并使用同一環(huán)境中的 Claude Code。在 Linux、WSL、macOS 終端檢查 Pythonpython3--versionWindows PowerShell 使用 Python 啟動(dòng)器檢查未安裝啟動(dòng)器時(shí)可用python --versionpy--version還需要 pipx用它管理這個(gè)命令行工具。缺少環(huán)境時(shí)按 Python 官方下載頁選擇表中支持的版本按 pipx 官方安裝說明完成安裝再檢查pipx --version claude --version要顯示 Git 信息還需讓git --version能正常運(yùn)行。2. 安裝軟件包下面的單行命令適用于 Bash、Zsh 和 PowerShellpipx install fbincon-claude-code-statusline pipx ensurepath執(zhí)行后重新打開終端讓 PATH 更新生效。安裝包名是fbincon-claude-code-statusline運(yùn)行命令是claude-statusline。Windows 將下文的命令名替換為claude-statusline.exe參數(shù)相同。3. 接入 Claude Code在新終端依次執(zhí)行claude-statusline --version claude-statusline install --dry-run claude-statusline install claude-statusline doctor第一條確認(rèn)工具可用--dry-run預(yù)覽接入修改install寫入接入配置doctor檢查當(dāng)前環(huán)境與集成狀態(tài)。軟件包安裝和 Claude Code 接入是兩個(gè)步驟。檢查通過后在受信任終端重啟 Claude Code底部應(yīng)出現(xiàn)狀態(tài)欄。已有第三方狀態(tài)欄或同名配置入口時(shí)先按沖突處理說明處理。三、先讀懂狀態(tài)欄里的信息信息主要含義模型與 effort當(dāng)前模型以及宿主提供的思考強(qiáng)度當(dāng)前目錄當(dāng)前會(huì)話所在的工作目錄Git分支、與上游的提交差距、工作區(qū)變化Context remaining當(dāng)前上下文窗口的剩余比例使用限額宿主提供的五小時(shí)、每周或網(wǎng)關(guān)額度Token當(dāng)前會(huì)話累計(jì)記錄的輸入、緩存和輸出用量Task total time當(dāng)前或最近一次人類任務(wù)的總耗時(shí)Git 中的↑N、↓N表示領(lǐng)先、落后上游的提交數(shù)●N是暫存文件數(shù)~N是未暫存文件數(shù)?N是未跟蹤文件數(shù)!N是沖突文件數(shù)。非 Git 目錄會(huì)省略這一項(xiàng)。Context 73% left表示上下文窗口還剩約 73%。它與賬戶限額、會(huì)話累計(jì) token 分別統(tǒng)計(jì)。tokens中hit是緩存讀取輸入miss是普通輸入與緩存創(chuàng)建之和out是輸出統(tǒng)計(jì)包含可發(fā)現(xiàn)的子 Agent transcript。任務(wù)計(jì)時(shí)包含排隊(duì)、用戶等待、所屬子 Agent 工作和主 Agent 收尾。?表示運(yùn)行?表示成功■表示中斷?表示失敗。需要排除已核實(shí)的用戶等待時(shí)可另選task-active-timer只有原生計(jì)時(shí)觀測(cè)完整時(shí)才顯示。這些字段依賴宿主輸入或本地記錄缺失時(shí)可能省略。完整口徑見顯示項(xiàng)與指標(biāo)定義。四、通過終端界面調(diào)整顯示內(nèi)容1. 先用獨(dú)立 TUI 配置在 Claude Code 外的真實(shí)終端運(yùn)行claude-statusline configure窗口至少需要 64×18。進(jìn)入后可以看到四個(gè)頁面頁面用途Main選擇主狀態(tài)欄條目調(diào)整順序Subagents配置子 Agent 獨(dú)立行Settings設(shè)置顏色、格式、目錄樣式、刷新行為及預(yù)設(shè)Layout設(shè)置分行、條目?jī)?yōu)先級(jí)和最大寬度圖 1Main 頁面。下方 Preview 使用固定樣例數(shù)據(jù)用于檢查排版?？梢韵仍?Main 頁選一個(gè)條目用 Space 開關(guān)再用左右方向鍵調(diào)整順序輸入文字可篩選條目。需要修改單項(xiàng)標(biāo)簽、圖標(biāo)或格式時(shí)選中后按 CtrlE。獨(dú)立外部 TUI 按鍵操作Tab / ShiftTab切換頁面↑ / ↓、Space、← / →選擇、開關(guān)、排序或調(diào)整設(shè)置值CtrlE / CtrlG打開逐項(xiàng)格式返回或取消輸入CtrlS完成字段輸入后保存完整草稿Esc先取消輸入未處于輸入狀態(tài)時(shí)放棄草稿退出Enter 在項(xiàng)目頁可保存在高級(jí)字段中用于編輯或確認(rèn)輸入。保存整份配置統(tǒng)一用 CtrlS更容易記住?；氐?Claude Code 后下一次狀態(tài)欄刷新會(huì)使用新配置。2. 在 Claude Code 內(nèi)啟動(dòng)配置下面兩條命令輸入到Claude Code 會(huì)話按需選擇一個(gè)命令打開位置Claude Code 版本/statusline-configure支持的外部終端中打開同一個(gè) TUI2.1.258/statusline-configure-native當(dāng)前會(huì)話內(nèi)的 Client 配置面板2.1.287外部入口在 Linux 使用 tmux 或 GNOME Terminal在 macOS 使用 tmux 或 Terminal.app在 Windows 使用新控制臺(tái)啟動(dòng)器不可用時(shí)使用獨(dú)立configure。會(huì)話內(nèi) Client 打開后先點(diǎn)擊面板區(qū)域再用鍵盤。它的保存方式是S 保存留頁、F 保存并退出、Q 放棄未保存修改取消字段輸入用 CtrlG。按頁面底部提示操作即可。各入口共享當(dāng)前用戶的配置對(duì)該配置目錄下的 Claude Code 項(xiàng)目生效。/statusline-config則提供問答配置會(huì)使用模型回合狀態(tài)欄渲染本身讀取宿主輸入和本地狀態(tài)不額外發(fā)起網(wǎng)絡(luò)請(qǐng)求或消耗模型 token。下面展示會(huì)話內(nèi)配置面板。截圖中的Preview 是固定樣例數(shù)據(jù)會(huì)話底部的主狀態(tài)欄顯示會(huì)話數(shù)據(jù)。Linux會(huì)話內(nèi) Main、Subagents、Settings、LayoutMain選擇主狀態(tài)欄條目并調(diào)整順序。Subagents配置子 Agent 獨(dú)立行及條目順序。Settings調(diào)整外觀、刷新行為與顯示格式。Layout設(shè)置分行、條目?jī)?yōu)先級(jí)與最大寬度。五、三組可以直接使用的配置以下命令都在系統(tǒng)終端執(zhí)行。前兩組是主欄的兩種選擇第三組單獨(dú)配置子 Agent 行。set-items會(huì)替換該欄啟用集合并確定順序想追加某項(xiàng)時(shí)用enable。1. 精簡(jiǎn)開發(fā)視圖claude-statusline config set-items model-with-effort current-dir git context-remaining task-timer claude-statusline config set directory-style home claude-statusline config set separator-style compact claude-statusline config show這組保留模型、目錄、Git、上下文余量和任務(wù)用時(shí)。home會(huì)將主目錄前綴縮寫為~compact使用緊湊分隔符show可確認(rèn)保存結(jié)果。如果希望主欄分為兩行接著執(zhí)行claude-statusline config layout explicit model-with-effort,current-dir,git context-remaining,task-timer每個(gè)參數(shù)表示一行逗號(hào)連接同行條目順序與剛才啟用的條目一致。在 Layout 頁也能設(shè)置行邊界并為重要條目分配較高優(yōu)先級(jí)、為長(zhǎng)目錄限制寬度。圖 2Layout 頁面截圖中的 Preview 為樣例數(shù)據(jù)。自動(dòng)布局會(huì)折行顯式布局在寬度不足時(shí)按限制截短并精簡(jiǎn)低優(yōu)先級(jí)項(xiàng)。2. 限額與 token 視圖claude-statusline config set-items five-hour-limit weekly-limit spend-limit tokens claude-statusline config layout auto適合主要關(guān)注用量的場(chǎng)景。spend-limit依賴宿主和網(wǎng)關(guān)提供的額度數(shù)據(jù)賬戶或端點(diǎn)未提供時(shí)會(huì)省略選擇顯示項(xiàng)不會(huì)讓缺失數(shù)據(jù)自動(dòng)出現(xiàn)。3. 子 Agent 狀態(tài)行子 Agent 行需要 Claude Code 2.1.205逐任務(wù) effort 需 2.1.214。默認(rèn)已啟用自定義行可設(shè)置為claude-statusline config subagents set-items status-elapsed name model-with-effort context-remaining task claude-statusline config set subagent-hide-completed on claude-statusline config set subagent-row-limit 6真實(shí)任務(wù)運(yùn)行子 Agent 時(shí)每行會(huì)展示對(duì)應(yīng)任務(wù)的狀態(tài)與用時(shí)、名稱、模型、上下文和任務(wù)標(biāo)簽。上述設(shè)置隱藏已完成代理最多顯示六行。主欄仍屬于主會(huì)話每條子 Agent 行使用自己的任務(wù)數(shù)據(jù)子 Agent 的tokens表示上下文占用。圖 3Subagents 頁面及樣例預(yù)覽展示子 Agent 行的可配置內(nèi)容。4. 用預(yù)設(shè)起步保存自己的方案也可以從minimal、developer、monitoring、multi-agent四套預(yù)設(shè)開始。例如先預(yù)覽再應(yīng)用開發(fā)預(yù)設(shè)claude-statusline config preset developer --dry-run claude-statusline config preset developer預(yù)設(shè)展開后仍可編輯。在 Settings 中調(diào)整顏色、數(shù)字和模型名稱格式Main/Subagents 中的 CtrlE 可覆蓋單項(xiàng)格式。滿意后導(dǎo)出到當(dāng)前目錄的新文件claude-statusline config export ./statusline.json在另一臺(tái)已安裝并接入工具的電腦上將文件放到當(dāng)前目錄先檢查再導(dǎo)入claude-statusline config import ./statusline.json --dry-run claude-statusline config import ./statusline.json文件已存在時(shí)導(dǎo)出請(qǐng)換一個(gè)文件名?？梢浦才渲冒@示設(shè)置及工具管理的刷新等選項(xiàng)運(yùn)行狀態(tài)和插件接入偏好需在各機(jī)器分別管理。六、按需開啟實(shí)時(shí)指標(biāo)2026.10.18 更新npm 版新安裝默認(rèn)關(guān)閉原生計(jì)時(shí)和高級(jí)實(shí)時(shí)采集并保留已有明確偏好。只啟用原生計(jì)時(shí)可執(zhí)行claude-statusline install --native-timing啟用完整采集使用下文的claude-statusline install --live-metrics。兩者均要求 Claude Code 2.1.289執(zhí)行后運(yùn)行doctor并重啟 Claude Code。以下原文保留其中“新安裝默認(rèn)采集原生計(jì)時(shí)”的描述適用于歷史 Python 版。需要查看運(yùn)行狀態(tài)、活動(dòng) Agent 數(shù)量、結(jié)構(gòu)化任務(wù)進(jìn)度和最近工具時(shí)先確認(rèn) Claude Code 為 2.1.289在系統(tǒng)終端執(zhí)行claude-statusline install --live-metrics claude-statusline config enable run-state permission-mode active-agents task-progress last-tool claude-statusline doctor檢查后重啟 Claude Code加載采集器后續(xù)運(yùn)行任務(wù)時(shí)觀察新增字段。這一步同時(shí)涉及采集器接入和顯示項(xiàng)選擇僅在編輯器中勾選字段還不夠。高級(jí)實(shí)時(shí)指標(biāo)默認(rèn)關(guān)閉與兼容宿主新安裝默認(rèn)采集的原生計(jì)時(shí)元數(shù)據(jù)分別管理。沒有有效觀測(cè)時(shí)顯示—有限覆蓋或最近觀測(cè)可能帶*。其中任務(wù)進(jìn)度來自結(jié)構(gòu)化任務(wù)記錄不能據(jù)此推算還剩多久。七、常見問題、升級(jí)與卸載2026.10.18 更新npm 版排查、更新、遷移與卸載以下新增說明適用于 v3.0.0 及之后Windows 使用claude-statusline.cmd。原 Python/pipx 說明保留在本節(jié)后半部分。1. npm 安裝后找不到命令全局安裝后先檢查軟件包與安裝前綴npm list --global --depth0 npm prefix --global確認(rèn) npm 的全局命令目錄已加入 PATH調(diào)整后重新打開終端。LinuxWSLmacOS 可用command -v claude-statusline核對(duì)入口Windows PowerShell 可用Get-Command claude-statusline.cmd。若仍指向 Python/pipx 舊版先按下方遷移步驟處理同名入口。2. 更新已全局安裝的 npm 版先退出 Claude Code 和配置編輯器再執(zhí)行npm install --global --ignore-scripts fbincon/claude-code-statusline claude-statusline --version claude-statusline install claude-statusline doctor檢查通過后重啟 Claude Code。重新執(zhí)行 npm 安裝命令會(huì)更新軟件包隨后仍需執(zhí)行install同步命令路徑、hooks、skills 和插件資源。pipx upgrade只管理歷史 Python 包不能更新到 v3.x。如果采用下方的獨(dú)立目錄安裝更新時(shí)保持同一個(gè)--prefix ./statusline-node通過同一 Node/JavaScript 入口執(zhí)行--version、install和doctor全局 npm 更新命令不更新該獨(dú)立目錄。3. 從 Python/pipx 遷移到 npm切換前先退出 Claude Code 和配置編輯器備份整個(gè) Claude 配置目錄默認(rèn)~/.claude使用CLAUDE_CONFIG_DIR時(shí)備份對(duì)應(yīng)目錄記錄原 Python 命令的絕對(duì)路徑與版本并保留原 pipx 環(huán)境用于回退。新舊版不要同時(shí)向同一配置目錄寫入。為避開 PATH 中已有的同名 Python 命令可先在一個(gè)長(zhǎng)期保留的位置使用獨(dú)立目錄安裝。以下命令從該位置執(zhí)行將新版安裝到./statusline-node并明確使用 Node 入口完成接入npm install --prefix ./statusline-node --ignore-scripts fbincon/claude-code-statusline3.1.0 node ./statusline-node/node_modules/fbincon/claude-code-statusline/bin/claude-statusline.js --version node ./statusline-node/node_modules/fbincon/claude-code-statusline/bin/claude-statusline.js install --dry-run node ./statusline-node/node_modules/fbincon/claude-code-statusline/bin/claude-statusline.js install node ./statusline-node/node_modules/fbincon/claude-code-statusline/bin/claude-statusline.js doctor使用自定義配置目錄時(shí)為上述install和doctor命令傳入相同的--config-dir。檢查通過后重啟 Claude Code接入會(huì)綁定實(shí)際 Node 和 JavaScript 入口因此使用期間須保留該安裝目錄和 Node 可執(zhí)行文件。獨(dú)立目錄安裝不會(huì)把終端里的claude-statusline自動(dòng)切換到新版后續(xù)配置、更新和卸載應(yīng)繼續(xù)通過上述node .../claude-statusline.js入口操作。已有顯示配置、明確的編輯器與采集偏好及無關(guān) Claude 設(shè)置會(huì)保留。不要用 npm--force覆蓋歸屬不明的同名命令。如需保留 Python 回退環(huán)境可繼續(xù)使用獨(dú)立目錄如需改用全局 npm 命令在新版驗(yàn)證通過后先用pipx list核實(shí)舊包名稱再用pipx uninstall fbincon-claude-code-statusline移除對(duì)應(yīng)舊包隨后按第二節(jié)完成全局 npm 安裝和接入。確認(rèn)全局版本接入正常后再刪除獨(dú)立安裝目錄。需要回退時(shí)按新版遷移與恢復(fù)指南恢復(fù)切換前兼容備份和原 Python 接入。4. 卸載 npm 版先退出 Claude Code 和配置編輯器在命令仍可用時(shí)移除接入再卸載軟件包。對(duì)于全局 npm 安裝claude-statusline uninstall --dry-run claude-statusline uninstall npm uninstall --global fbincon/claude-code-statusline僅在接入卸載成功后執(zhí)行最后一條。工具會(huì)移除歸屬本工具的接入資源保留第三方設(shè)置以及顯示配置、偏好、緩存、任務(wù)狀態(tài)和備份便于重裝復(fù)用。若使用獨(dú)立目錄安裝通過同一node .../claude-statusline.js入口依次執(zhí)行uninstall --dry-run和uninstall確認(rèn)成功后再刪除當(dāng)初專門創(chuàng)建的statusline-node安裝目錄。npm uninstall --global不負(fù)責(zé)移除這類獨(dú)立目錄安裝。以下保留原常見問題、Python/pipx 升級(jí)與卸載內(nèi)容。涉及 pipx 或.exe的步驟適用于 v2.0.0 及之前npm 版請(qǐng)使用以上更新說明。找不到命令先運(yùn)行pipx list確認(rèn)包已安裝再執(zhí)行pipx ensurepath并重新打開終端。Windows 使用claude-statusline.exe。狀態(tài)欄沒出現(xiàn)運(yùn)行claude-statusline doctor檢查 PATH、接入是否完成、顯示項(xiàng)是否為空以及宿主是否禁用了 hooks/statusline接入修復(fù)后重啟 Claude Code。若提示因信任被跳過按宿主提示完成對(duì)應(yīng)信任操作。配置入口不可用檢查claude --version、安裝偏好和插件狀態(tài)。不兼容入口會(huì)暫掛宿主升級(jí)后重新執(zhí)行install與doctor。macOS 的會(huì)話內(nèi) Client 仍有已記錄的交互限制可使用獨(dú)立 TUI 或 CLI。部分?jǐn)?shù)據(jù)暫時(shí)缺失首次真實(shí)模型響應(yīng)前transcript 或用量信息可能尚未產(chǎn)生限額和 effort 等字段也取決于宿主是否提供。doctor的[WARN]表示有降級(jí)情況需結(jié)合具體提示判斷。升級(jí)時(shí)先退出 Claude Code在終端執(zhí)行pipx upgrade fbincon-claude-code-statusline claude-statusline install claude-statusline doctor隨后重啟 Claude Code。軟件包升級(jí)后還要同步接入。若使用過本倉庫舊分發(fā)名先核實(shí)安裝來源再按包名遷移說明處理。卸載時(shí)先退出 Claude Code再移除接入最后卸載軟件包c(diǎn)laude-statusline uninstall --dry-run claude-statusline uninstall pipx uninstall fbincon-claude-code-statusline顯示配置、運(yùn)行狀態(tài)和備份會(huì)保留便于重裝復(fù)用。更多排查步驟見完整使用指南。八、項(xiàng)目與文檔入口項(xiàng)目使用 MIT 許可證。源碼、發(fā)行包和詳細(xì)文檔可從以下入口獲取GitHub 主倉庫Gitee 同步倉庫npm 軟件包TypeScript 版中文使用指南CLI 參考保留 Python 版供參考PyPI 軟件包最后一個(gè)版本為 v2.0.0v2.0.0 中文使用指南最后一個(gè) Python 版歡迎結(jié)合自己的開發(fā)習(xí)慣調(diào)整顯示內(nèi)容。