狀態列是 Claude Code 底部的可自訂列,可執行您設定的任何 shell 指令碼。它透過 stdin 接收 JSON 工作階段資料,並顯示您的指令碼列印的任何內容,為您提供 context 使用情況、成本、git 狀態或任何其他您想追蹤的內容的持久、一目瞭然的檢視。 狀態列在以下情況下很有用:Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
- 您想在工作時監控 context window 使用情況
- 您需要追蹤工作階段成本
- 您跨多個工作階段工作,需要區分它們
- 您希望 git 分支和狀態始終可見

設定狀態列
使用/statusline 命令讓 Claude Code 為您產生指令碼,或手動建立指令碼並將其新增到您的設定。
使用 /statusline 命令
/statusline 命令接受描述您想顯示內容的自然語言指令。Claude Code 在 ~/.claude/ 中產生指令碼檔案並自動更新您的設定:
手動設定狀態列
將statusLine 欄位新增到您的使用者設定(~/.claude/settings.json,其中 ~ 是您的主目錄)或專案設定。將 type 設定為 "command",並將 command 指向指令碼路徑或內聯 shell 命令。如需建立指令碼的完整逐步說明,請參閱逐步建立狀態列。
command 欄位在 shell 中執行,因此您也可以使用內聯命令而不是指令碼檔案。此範例使用 jq 解析 JSON 輸入並顯示模型名稱和 context 百分比:
padding 欄位為狀態列內容新增額外的水平間距(以字元為單位)。預設為 0。此填充是在介面的內建間距之外,因此它控制相對縮排而不是距離終端邊緣的絕對距離。
可選的 refreshInterval 欄位除了事件驅動的更新外,每 N 秒重新執行一次您的命令。最小值為 1。當您的狀態列顯示基於時間的資料(例如時鐘)或背景子代理在主工作階段閒置時變更 git 狀態時,請設定此項。保持未設定以僅在事件上執行。
可選的 hideVimModeIndicator 欄位會隱藏提示下方的內建 -- INSERT -- 文字。當您的指令碼自行呈現 vim.mode 時,請將此設定為 true,以便模式不會顯示兩次。
停用狀態列
執行/statusline 並要求它移除或清除您的狀態列(例如 /statusline delete、/statusline clear、/statusline remove it)。您也可以手動從 settings.json 中刪除 statusLine 欄位。
逐步建立狀態列
此逐步說明透過手動建立顯示目前模型、工作目錄和 context window 使用百分比的狀態列來展示幕後發生的情況。使用
/statusline和您想要的內容描述會自動為您設定所有這些。
建立讀取 JSON 並列印輸出的指令碼
Claude Code 透過 stdin 將 JSON 資料傳送到您的指令碼。此指令碼使用
jq(一個您可能需要安裝的命令列 JSON 解析器)來提取模型名稱、目錄和 context 百分比,然後列印格式化的行。將此儲存到 ~/.claude/statusline.sh(其中 ~ 是您的主目錄,例如 macOS 上的 /Users/username 或 Linux 上的 /home/username):狀態列如何運作
Claude Code 執行您的指令碼並透過 stdin 將 JSON 工作階段資料 傳送給它。您的指令碼讀取 JSON、提取所需內容並將文字列印到 stdout。Claude Code 顯示您的指令碼列印的任何內容。 何時更新 您的指令碼在每個新的助手訊息之後、/compact 完成後、權限模式變更時或 vim 模式切換時執行。更新在 300ms 處進行去抖動,這意味著快速變更會批次在一起,您的指令碼在事情穩定後執行一次。如果在您的指令碼仍在執行時觸發新的更新,則會取消進行中的執行。如果您編輯指令碼,變更在您與 Claude Code 的下一次互動觸發更新之前不會出現。
這些觸發器在主工作階段閒置時可能會安靜,例如當協調器等待背景子代理時。為了在閒置期間保持基於時間或外部來源的片段最新,請將 refreshInterval 設定為也在固定計時器上重新執行命令。
您的指令碼可以輸出什麼
- 多行:每個
echo或print陳述式顯示為單獨的行。請參閱多行範例。 - 顏色:使用 ANSI 逃逸碼,例如
\033[32m表示綠色(終端必須支援它們)。請參閱 git 狀態範例。 - 連結:使用 OSC 8 逃逸序列 使文字可點擊(macOS 上為 Cmd+click,Windows/Linux 上為 Ctrl+click)。需要支援超連結的終端,例如 iTerm2、Kitty 或 WezTerm。請參閱可點擊連結範例。
狀態列在本地執行,不消耗 API 令牌。在某些 UI 互動期間,它會暫時隱藏,包括自動完成建議、說明功能表和權限提示。
可用資料
Claude Code 透過 stdin 將以下 JSON 欄位傳送到您的指令碼:| 欄位 | 描述 |
|---|---|
model.id, model.display_name | 目前的模型識別碼和顯示名稱 |
cwd, workspace.current_dir | 目前的工作目錄。兩個欄位包含相同的值;workspace.current_dir 因與 workspace.project_dir 一致而首選。 |
workspace.project_dir | 啟動 Claude Code 的目錄,如果工作階段期間工作目錄變更,可能與 cwd 不同 |
workspace.added_dirs | 透過 /add-dir 或 --add-dir 新增的其他目錄。如果未新增任何目錄,則為空陣列 |
workspace.git_worktree | 當目前目錄位於使用 git worktree add 建立的連結 worktree 內時的 Git worktree 名稱。在主工作樹中不存在。對任何 git worktree 都會填入,不同於 worktree.* 僅適用於 --worktree 工作階段 |
cost.total_cost_usd | 工作階段總成本(美元),在用戶端計算。可能與您的實際帳單不同 |
cost.total_duration_ms | 自工作階段開始以來的總掛鐘時間(毫秒) |
cost.total_api_duration_ms | 等待 API 回應所花費的總時間(毫秒) |
cost.total_lines_added, cost.total_lines_removed | 變更的程式碼行數 |
context_window.total_input_tokens, context_window.total_output_tokens | 目前在 context window 中的令牌計數,來自最近的 API 回應。輸入包括快取讀取和寫入。v2.1.132 之前這些是累積工作階段總計 |
context_window.context_window_size | 最大 context window 大小(令牌)。預設為 200000,或具有擴展 context 的模型為 1000000。 |
context_window.used_percentage | 預先計算的已使用 context window 百分比 |
context_window.remaining_percentage | 預先計算的剩餘 context window 百分比 |
context_window.current_usage | 最後一次 API 呼叫中的令牌計數,在 context window 欄位中描述 |
exceeds_200k_tokens | 最近 API 回應中的總令牌計數(輸入、快取和輸出令牌合併)是否超過 200k。這是一個固定閾值,與實際 context window 大小無關。 |
effort.level | 目前的推理努力等級(low、medium、high、xhigh 或 max)。反映即時工作階段值,包括工作階段中途的 /effort 變更。當目前模型不支援努力參數時不存在 |
thinking.enabled | 是否為工作階段啟用擴展思考 |
rate_limits.five_hour.used_percentage, rate_limits.seven_day.used_percentage | 消耗的 5 小時或 7 天速率限制的百分比,從 0 到 100 |
rate_limits.five_hour.resets_at, rate_limits.seven_day.resets_at | 5 小時或 7 天速率限制視窗重設時的 Unix 紀元秒數 |
session_id | 唯一的工作階段識別碼 |
session_name | 使用 --name 旗標或 /rename 設定的自訂工作階段名稱。如果未設定自訂名稱,則不存在 |
transcript_path | 對話記錄檔案的路徑 |
version | Claude Code 版本 |
output_style.name | 目前輸出樣式的名稱 |
vim.mode | 啟用 vim 模式時的目前 vim 模式(NORMAL、INSERT、VISUAL 或 VISUAL LINE) |
agent.name | 使用 --agent 旗標或設定的代理設定執行時的代理名稱 |
worktree.name | 作用中 worktree 的名稱。僅在 --worktree 工作階段期間出現 |
worktree.path | worktree 目錄的絕對路徑 |
worktree.branch | worktree 的 Git 分支名稱(例如 "worktree-my-feature")。對於基於 hook 的 worktree 不存在 |
worktree.original_cwd | Claude 進入 worktree 之前所在的目錄 |
worktree.original_branch | 進入 worktree 之前簽出的 Git 分支。對於基於 hook 的 worktree 不存在 |
完整 JSON 架構
完整 JSON 架構
您的狀態列命令透過 stdin 接收此 JSON 結構:可能不存在的欄位(不在 JSON 中):
session_name:僅在使用--name或/rename設定自訂名稱時出現workspace.git_worktree:僅當目前目錄位於連結 git worktree 內時出現effort:僅當目前模型支援推理努力參數時出現vim:僅在啟用 vim 模式時出現agent:僅在使用--agent旗標或設定的代理設定執行時出現worktree:僅在--worktree工作階段期間出現。存在時,branch和original_branch對於基於 hook 的 worktree 也可能不存在rate_limits:僅對 Claude.ai 訂閱者(Pro/Max)在工作階段中第一次 API 回應後出現。每個視窗(five_hour、seven_day)可能獨立不存在。使用jq -r '.rate_limits.five_hour.used_percentage // empty'以優雅地處理不存在的情況。
null 的欄位:context_window.current_usage:在工作階段中第一次 API 呼叫之前為null,以及在/compact之後直到下一次 API 呼叫重新填入為止context_window.used_percentage,context_window.remaining_percentage:在工作階段早期可能為null
Context window 欄位
context_window 物件描述來自最近 API 回應的即時 context window。自 v2.1.132 起,total_input_tokens 和 total_output_tokens 反映目前 context 使用情況,而非累積工作階段總計。
- 合併總計(
total_input_tokens,total_output_tokens):目前在 context window 中的令牌。total_input_tokens是input_tokens、cache_creation_input_tokens和cache_read_input_tokens的總和;total_output_tokens是最近回應中的輸出令牌。在第一次 API 回應之前兩者都是0。 - 按元件使用情況(
current_usage):相同的令牌計數按類別分解。當您需要將快取命中與新輸入分開時,請使用此項。
current_usage 物件包含:
input_tokens:目前 context 中的輸入令牌output_tokens:產生的輸出令牌cache_creation_input_tokens:寫入快取的令牌cache_read_input_tokens:從快取讀取的令牌
used_percentage 欄位僅從輸入令牌計算:input_tokens + cache_creation_input_tokens + cache_read_input_tokens。它不包括 output_tokens。
如果您從 current_usage 手動計算 context 百分比,請使用相同的僅輸入公式以符合 used_percentage。
current_usage 物件在工作階段中第一次 API 呼叫之前為 null,以及在 /compact 之後直到下一次 API 呼叫重新填入為止再次為 null。
範例
這些範例展示常見的狀態列模式。若要使用任何範例:- 將指令碼儲存到檔案,例如
~/.claude/statusline.sh(或.py/.js) - 使其可執行:
chmod +x ~/.claude/statusline.sh - 將路徑新增到您的設定
jq 來解析 JSON。Python 和 Node.js 具有內建的 JSON 解析。
Context window 使用情況
顯示目前模型和 context window 使用情況,帶有視覺進度列。每個指令碼從 stdin 讀取 JSON,提取used_percentage 欄位,並建立一個 10 字元的列,其中填充的塊(▓)代表使用情況:

Git 狀態與顏色
顯示 git 分支,帶有暫存和修改檔案的顏色編碼指示器。此指令碼使用 ANSI 逃逸碼表示終端顏色:\033[32m 是綠色,\033[33m 是黃色,\033[0m 重設為預設值。

成本和持續時間追蹤
追蹤您的工作階段 API 成本和經過的時間。cost.total_cost_usd 欄位累積目前工作階段中所有 API 呼叫的估計成本。cost.total_duration_ms 欄位測量自工作階段開始以來的總經過時間,而 cost.total_api_duration_ms 僅追蹤等待 API 回應所花費的時間。
每個指令碼將成本格式化為貨幣,並將毫秒轉換為分鐘和秒:

顯示多行
您的指令碼可以輸出多行以建立更豐富的顯示。每個echo 陳述式在狀態區域中產生單獨的行。

print 或 echo 陳述式建立單獨的行:
可點擊的連結
此範例建立指向您的 GitHub 儲存庫的可點擊連結。它讀取 git 遠端 URL,使用sed 將 SSH 格式轉換為 HTTPS,並將儲存庫名稱包裝在 OSC 8 逃逸碼中。按住 Cmd(macOS)或 Ctrl(Windows/Linux)並點擊以在瀏覽器中開啟連結。

printf '%b',它比 echo -e 更可靠地跨不同 shell 解釋反斜杠逃逸:
速率限制使用情況
在狀態列中顯示 Claude.ai 訂閱速率限制使用情況。rate_limits 物件包含 five_hour(5 小時滾動視窗)和 seven_day(每週)視窗。每個視窗提供 used_percentage(0-100)和 resets_at(Unix 紀元秒,視窗重設時)。
此欄位僅對 Claude.ai 訂閱者(Pro/Max)在第一次 API 回應後出現。每個指令碼優雅地處理不存在的欄位:
快取昂貴的操作
您的狀態列指令碼在活躍工作階段期間頻繁執行。git status 或 git diff 等命令可能很慢,特別是在大型儲存庫中。此範例將 git 資訊快取到臨時檔案,並且僅每 5 秒重新整理一次。
快取檔案名稱需要在工作階段內的狀態列呼叫中保持穩定,但在工作階段之間保持唯一,以便不同儲存庫中的並行工作階段不會讀取彼此的快取 git 狀態。基於程序的識別碼(如 $$、os.getpid() 或 process.pid)在每次呼叫時都會變更,並會破壞快取。改用 JSON 輸入中的 session_id:它在工作階段的生命週期內保持穩定,並且每個工作階段都是唯一的。
每個指令碼在執行 git 命令之前檢查快取檔案是否遺漏或超過 5 秒:
Windows 設定
在 Windows 上,Claude Code 透過 Git Bash 執行狀態列命令(如果已安裝 Git Bash),或在 Git Bash 不存在時透過 PowerShell 執行。若要執行 PowerShell 指令碼作為您的狀態列,請透過powershell 呼叫它;這在任一 shell 中都有效:
子代理狀態列
subagentStatusLine 設定為子代理面板中顯示的每個子代理呈現自訂行主體。使用它來用您自己的格式化取代預設的 name · description · token count 行。
columns(可用行寬度)和 tasks 陣列,其中每個任務具有 id、name、type、status、description、label、startTime、tokenCount、tokenSamples 和 cwd。
將一個 JSON 行寫入 stdout,每行您想要覆蓋,形式為 {"id": "<task id>", "content": "<row body>"} 。content 字串按原樣呈現,包括 ANSI 顏色和 OSC 8 超連結。省略任務的 id 以保持該行的預設呈現;發出空 content 字串以隱藏它。
適用於 statusLine 的相同信任和 disableAllHooks 閘門也適用於此。外掛程式可以在其 settings.json 中提供預設 subagentStatusLine。
提示
- 使用模擬輸入測試:
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh - 保持輸出簡短:狀態列寬度有限,因此長輸出可能會被截斷或換行不當
- 快取慢速操作:您的指令碼在活躍工作階段期間頻繁執行,因此
git status等命令可能會導致延遲。請參閱快取範例以瞭解如何處理此問題。
疑難排解
狀態列未出現- 驗證您的指令碼是否可執行:
chmod +x ~/.claude/statusline.sh - 檢查您的指令碼是否輸出到 stdout 而不是 stderr
- 手動執行您的指令碼以驗證它產生輸出
- 如果
disableAllHooks在您的設定中設定為true,狀態列也會被停用。移除此設定或將其設定為false以重新啟用。 - 執行
claude --debug以記錄工作階段中第一次狀態列呼叫的結束代碼和 stderr - 要求 Claude 讀取您的設定檔案並直接執行
statusLine命令以顯示錯誤
-- 或空值
- 欄位在第一次 API 回應完成之前可能為
null - 在您的指令碼中使用後備(例如 jq 中的
// 0)處理 null 值 - 如果多個訊息後值仍為空,請重新啟動 Claude Code
- 使用
used_percentage以取得最簡單的準確 context 狀態 - Context 百分比可能與
/context輸出不同,因為每個計算時間不同
- 驗證您的終端支援 OSC 8 超連結(iTerm2、Kitty、WezTerm)
- Terminal.app 不支援可點擊連結
-
如果連結文字出現但不可點擊,Claude Code 可能未在您的終端中偵測到超連結支援。這通常會影響 Windows Terminal 和其他不在自動偵測清單中的模擬器。設定
FORCE_HYPERLINK環境變數以在啟動 Claude Code 之前覆蓋偵測:在 PowerShell 中,先在目前工作階段中設定變數: - SSH 和 tmux 工作階段可能根據設定去除 OSC 序列
-
如果逃逸序列顯示為文字(如
\e]8;;),請使用printf '%b'而不是echo -e以獲得更可靠的逃逸處理
- 複雜的逃逸序列(ANSI 顏色、OSC 8 連結)如果與其他 UI 更新重疊,偶爾會導致輸出損壞
- 如果您看到損壞的文字,請嘗試簡化您的指令碼為純文字輸出
- 帶有逃逸碼的多行狀態列比單行純文字更容易出現呈現問題
- 狀態列命令僅在您已接受目前目錄的工作區信任對話時執行。因為
statusLine執行 shell 命令,它需要與 hooks 和其他執行 shell 的設定相同的信任接受。 - 如果未接受信任,您將看到通知
statusline skipped · restart to fix而不是您的狀態列輸出。重新啟動 Claude Code 並接受信任提示以啟用它。
- 以非零代碼結束或不產生輸出的指令碼會導致狀態列變為空白
- 慢速指令碼會阻止狀態列更新,直到它們完成。保持指令碼快速以避免過時的輸出。
- 如果在慢速指令碼執行時觸發新的更新,進行中的指令碼會被取消
- 在設定之前使用模擬輸入獨立測試您的指令碼
- 系統通知(如 MCP 伺服器錯誤和自動更新)顯示在與您的狀態列相同行的右側。暫時性通知(例如 context-low 警告)也會在此區域循環。
- 啟用詳細模式會在此區域新增令牌計數器
- 在狹窄的終端上,這些通知可能會截斷您的狀態列輸出