跳轉到主要內容
狀態列是 Claude Code 底部的可自訂列,可執行您設定的任何 shell 指令碼。它透過 stdin 接收 JSON 工作階段資料,並顯示您的指令碼列印的任何內容,為您提供 context 使用情況、成本、git 狀態或任何其他您想追蹤的內容的持久、一目瞭然的檢視。 狀態列在以下情況下很有用:
  • 您想在工作時監控 context window 使用情況
  • 您需要追蹤工作階段成本
  • 您跨多個工作階段工作,需要區分它們
  • 您希望 git 分支和狀態始終可見
以下是一個多行狀態列的範例,在第一行顯示 git 資訊,在第二行顯示顏色編碼的 context 列。
多行狀態列,在第一行顯示模型名稱、目錄、git 分支,在第二行顯示 context 使用進度列、成本和持續時間
本頁面介紹設定基本狀態列、說明資料如何從 Claude Code 流向您的指令碼、列出您可以顯示的所有欄位,並提供常見模式的現成範例,例如 git 狀態、成本追蹤和進度列。

設定狀態列

使用/statusline 命令讓 Claude Code 為您產生指令碼,或手動建立指令碼並將其新增到您的設定。

使用 /statusline 命令

/statusline 命令接受描述您想顯示內容的自然語言指令。Claude Code 在 ~/.claude/ 中產生指令碼檔案並自動更新您的設定:
/statusline show model name and context percentage with a progress bar

手動設定狀態列

statusLine 欄位新增到您的使用者設定(~/.claude/settings.json,其中 ~ 是您的主目錄)或專案設定。將 type 設定為 "command",並將 command 指向指令碼路徑或內聯 shell 命令。如需建立指令碼的完整逐步說明,請參閱逐步建立狀態列
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}
command 欄位在 shell 中執行,因此您也可以使用內聯命令而不是指令碼檔案。此範例使用 jq 解析 JSON 輸入並顯示模型名稱和 context 百分比:
{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}
可選的 padding 欄位為狀態列內容新增額外的水平間距(以字元為單位)。預設為 0。此填充是在介面的內建間距之外,因此它控制相對縮排而不是距離終端邊緣的絕對距離。

停用狀態列

執行 /statusline 並要求它移除或清除您的狀態列(例如 /statusline delete/statusline clear/statusline remove it)。您也可以手動從 settings.json 中刪除 statusLine 欄位。

逐步建立狀態列

此逐步說明透過手動建立顯示目前模型、工作目錄和 context window 使用百分比的狀態列來展示幕後發生的情況。
使用/statusline和您想要的內容描述會自動為您設定所有這些。
這些範例使用 Bash 指令碼,適用於 macOS 和 Linux。在 Windows 上,請參閱 Windows 設定以取得 PowerShell 和 Git Bash 範例。
狀態列顯示模型名稱、目錄和 context 百分比
1

建立讀取 JSON 並列印輸出的指令碼

Claude Code 透過 stdin 將 JSON 資料傳送到您的指令碼。此指令碼使用 jq(一個您可能需要安裝的命令列 JSON 解析器)來提取模型名稱、目錄和 context 百分比,然後列印格式化的行。將此儲存到 ~/.claude/statusline.sh(其中 ~ 是您的主目錄,例如 macOS 上的 /Users/username 或 Linux 上的 /home/username):
#!/bin/bash
# Read JSON data that Claude Code sends to stdin
input=$(cat)

# Extract fields using jq
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# The "// 0" provides a fallback if the field is null
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# Output the status line - ${DIR##*/} extracts just the folder name
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"
2

使其可執行

將指令碼標記為可執行,以便您的 shell 可以執行它:
chmod +x ~/.claude/statusline.sh
3

新增到設定

告訴 Claude Code 執行您的指令碼作為狀態列。將此設定新增到 ~/.claude/settings.json,它將 type 設定為 "command"(意思是「執行此 shell 命令」)並將 command 指向您的指令碼:
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}
您的狀態列出現在介面底部。設定會自動重新載入,但變更在您與 Claude Code 的下一次互動之前不會出現。

狀態列如何運作

Claude Code 執行您的指令碼並透過 stdin 將 JSON 工作階段資料傳送給它。您的指令碼讀取 JSON、提取所需內容並將文字列印到 stdout。Claude Code 顯示您的指令碼列印的任何內容。 何時更新 您的指令碼在每個新的助手訊息之後、權限模式變更時或 vim 模式切換時執行。更新在 300ms 處進行去抖動,這意味著快速變更會批次在一起,您的指令碼在事情穩定後執行一次。如果在您的指令碼仍在執行時觸發新的更新,則會取消進行中的執行。如果您編輯指令碼,變更在您與 Claude Code 的下一次互動觸發更新之前不會出現。 您的指令碼可以輸出什麼
  • 多行:每個 echoprint 陳述式顯示為單獨的行。請參閱多行範例
  • 顏色:使用 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 不同
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.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 大小無關。
session_id唯一的工作階段識別碼
transcript_path對話記錄檔案的路徑
versionClaude Code 版本
output_style.name目前輸出樣式的名稱
vim.mode啟用 vim 模式時的目前 vim 模式(NORMALINSERT
agent.name使用 --agent 旗標或設定的代理設定執行時的代理名稱
worktree.name作用中 worktree 的名稱。僅在 --worktree 工作階段期間出現
worktree.pathworktree 目錄的絕對路徑
worktree.branchworktree 的 Git 分支名稱(例如 "worktree-my-feature")。對於基於 hook 的 worktree 不存在
worktree.original_cwdClaude 進入 worktree 之前所在的目錄
worktree.original_branch進入 worktree 之前簽出的 Git 分支。對於基於 hook 的 worktree 不存在
您的狀態列命令透過 stdin 接收此 JSON 結構:
{
  "cwd": "/current/working/directory",
  "session_id": "abc123...",
  "transcript_path": "/path/to/transcript.jsonl",
  "model": {
    "id": "claude-opus-4-6",
    "display_name": "Opus"
  },
  "workspace": {
    "current_dir": "/current/working/directory",
    "project_dir": "/original/project/directory"
  },
  "version": "1.0.80",
  "output_style": {
    "name": "default"
  },
  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000,
    "total_api_duration_ms": 2300,
    "total_lines_added": 156,
    "total_lines_removed": 23
  },
  "context_window": {
    "total_input_tokens": 15234,
    "total_output_tokens": 4521,
    "context_window_size": 200000,
    "used_percentage": 8,
    "remaining_percentage": 92,
    "current_usage": {
      "input_tokens": 8500,
      "output_tokens": 1200,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 2000
    }
  },
  "exceeds_200k_tokens": false,
  "vim": {
    "mode": "NORMAL"
  },
  "agent": {
    "name": "security-reviewer"
  },
  "worktree": {
    "name": "my-feature",
    "path": "/path/to/.claude/worktrees/my-feature",
    "branch": "worktree-my-feature",
    "original_cwd": "/path/to/project",
    "original_branch": "main"
  }
}
可能不存在的欄位(不在 JSON 中):
  • vim:僅在啟用 vim 模式時出現
  • agent:僅在使用 --agent 旗標或設定的代理設定執行時出現
  • worktree:僅在 --worktree 工作階段期間出現。存在時,branchoriginal_branch 對於基於 hook 的 worktree 也可能不存在
可能為 null 的欄位
  • context_window.current_usage:在工作階段中第一次 API 呼叫之前為 null
  • context_window.used_percentage, context_window.remaining_percentage:在工作階段早期可能為 null
在您的指令碼中使用條件存取處理遺漏的欄位,並使用後備預設值處理 null 值。

Context window 欄位

context_window 物件提供兩種追蹤 context 使用情況的方式:
  • 累積總計total_input_tokens, total_output_tokens):整個工作階段中所有令牌的總和,用於追蹤總消耗
  • 目前使用情況current_usage):最後一次 API 呼叫中的令牌計數,使用此來取得準確的 context 百分比,因為它反映實際的 context 狀態
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

範例

這些範例展示常見的狀態列模式。若要使用任何範例:
  1. 將指令碼儲存到檔案,例如 ~/.claude/statusline.sh(或 .py/.js
  2. 使其可執行:chmod +x ~/.claude/statusline.sh
  3. 將路徑新增到您的設定
Bash 範例使用 jq 來解析 JSON。Python 和 Node.js 具有內建的 JSON 解析。

Context window 使用情況

顯示目前模型和 context window 使用情況,帶有視覺進度列。每個指令碼從 stdin 讀取 JSON,提取 used_percentage 欄位,並建立一個 10 字元的列,其中填充的塊(▓)代表使用情況:
狀態列顯示模型名稱和帶有百分比的進度列
#!/bin/bash
# Read all of stdin into a variable
input=$(cat)

# Extract fields with jq, "// 0" provides fallback for null
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# Build progress bar: printf -v creates a run of spaces, then
# ${var// /▓} replaces each space with a block character
BAR_WIDTH=10
FILLED=$((PCT * BAR_WIDTH / 100))
EMPTY=$((BAR_WIDTH - FILLED))
BAR=""
[ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /▓}"
[ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /░}"

echo "[$MODEL] $BAR $PCT%"

Git 狀態與顏色

顯示 git 分支,帶有暫存和修改檔案的顏色編碼指示器。此指令碼使用 ANSI 逃逸碼表示終端顏色:\033[32m 是綠色,\033[33m 是黃色,\033[0m 重設為預設值。
狀態列顯示模型、目錄、git 分支和暫存和修改檔案的彩色指示器
每個指令碼檢查目前目錄是否是 git 儲存庫,計算暫存和修改檔案,並顯示顏色編碼的指示器:
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')

GREEN='\033[32m'
YELLOW='\033[33m'
RESET='\033[0m'

if git rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
    MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')

    GIT_STATUS=""
    [ "$STAGED" -gt 0 ] && GIT_STATUS="${GREEN}+${STAGED}${RESET}"
    [ "$MODIFIED" -gt 0 ] && GIT_STATUS="${GIT_STATUS}${YELLOW}~${MODIFIED}${RESET}"

    echo -e "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH $GIT_STATUS"
else
    echo "[$MODEL] 📁 ${DIR##*/}"
fi

成本和持續時間追蹤

追蹤您的工作階段 API 成本和經過的時間。cost.total_cost_usd 欄位累積目前工作階段中所有 API 呼叫的成本。cost.total_duration_ms 欄位測量自工作階段開始以來的總經過時間,而 cost.total_api_duration_ms 僅追蹤等待 API 回應所花費的時間。 每個指令碼將成本格式化為貨幣,並將毫秒轉換為分鐘和秒:
狀態列顯示模型名稱、工作階段成本和持續時間
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

COST_FMT=$(printf '$%.2f' "$COST")
DURATION_SEC=$((DURATION_MS / 1000))
MINS=$((DURATION_SEC / 60))
SECS=$((DURATION_SEC % 60))

echo "[$MODEL] 💰 $COST_FMT | ⏱️ ${MINS}m ${SECS}s"

顯示多行

您的指令碼可以輸出多行以建立更豐富的顯示。每個 echo 陳述式在狀態區域中產生單獨的行。
多行狀態列,在第一行顯示模型名稱、目錄、git 分支,在第二行顯示 context 使用進度列、成本和持續時間
此範例結合了多種技術:基於閾值的顏色(70% 以下為綠色,70-89% 為黃色,90%+ 為紅色)、進度列和 git 分支資訊。每個 printecho 陳述式建立單獨的行:
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'

# Pick bar color based on context usage
if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"
elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"
else BAR_COLOR="$GREEN"; fi

FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"

MINS=$((DURATION_MS / 60000)); SECS=$(((DURATION_MS % 60000) / 1000))

BRANCH=""
git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=" | 🌿 $(git branch --show-current 2>/dev/null)"

echo -e "${CYAN}[$MODEL]${RESET} 📁 ${DIR##*/}$BRANCH"
COST_FMT=$(printf '$%.2f' "$COST")
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ⏱️ ${MINS}m ${SECS}s"

可點擊的連結

此範例建立指向您的 GitHub 儲存庫的可點擊連結。它讀取 git 遠端 URL,使用 sed 將 SSH 格式轉換為 HTTPS,並將儲存庫名稱包裝在 OSC 8 逃逸碼中。按住 Cmd(macOS)或 Ctrl(Windows/Linux)並點擊以在瀏覽器中開啟連結。
狀態列顯示指向 GitHub 儲存庫的可點擊連結
每個指令碼取得 git 遠端 URL,將 SSH 格式轉換為 HTTPS,並將儲存庫名稱包裝在 OSC 8 逃逸碼中。Bash 版本使用 printf '%b',它比 echo -e 更可靠地跨不同 shell 解釋反斜杠逃逸:
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')

# Convert git SSH URL to HTTPS
REMOTE=$(git remote get-url origin 2>/dev/null | sed 's/[email protected]:/https:\/\/github.com\//' | sed 's/\.git$//')

if [ -n "$REMOTE" ]; then
    REPO_NAME=$(basename "$REMOTE")
    # OSC 8 format: \e]8;;URL\a then TEXT then \e]8;;\a
    # printf %b interprets escape sequences reliably across shells
    printf '%b' "[$MODEL] 🔗 \e]8;;${REMOTE}\a${REPO_NAME}\e]8;;\a\n"
else
    echo "[$MODEL]"
fi

快取昂貴的操作

您的狀態列指令碼在活躍工作階段期間頻繁執行。git statusgit diff 等命令可能很慢,特別是在大型儲存庫中。此範例將 git 資訊快取到臨時檔案,並且僅每 5 秒重新整理一次。 為快取檔案使用穩定的固定檔案名,例如 /tmp/statusline-git-cache。每個狀態列呼叫作為新程序執行,因此基於程序的識別碼(如 $$os.getpid()process.pid)每次都產生不同的值,快取永遠不會被重複使用。 每個指令碼在執行 git 命令之前檢查快取檔案是否遺漏或超過 5 秒:
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')

CACHE_FILE="/tmp/statusline-git-cache"
CACHE_MAX_AGE=5  # seconds

cache_is_stale() {
    [ ! -f "$CACHE_FILE" ] || \
    # stat -f %m is macOS, stat -c %Y is Linux
    [ $(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0))) -gt $CACHE_MAX_AGE ]
}

if cache_is_stale; then
    if git rev-parse --git-dir > /dev/null 2>&1; then
        BRANCH=$(git branch --show-current 2>/dev/null)
        STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
        MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
        echo "$BRANCH|$STAGED|$MODIFIED" > "$CACHE_FILE"
    else
        echo "||" > "$CACHE_FILE"
    fi
fi

IFS='|' read -r BRANCH STAGED MODIFIED < "$CACHE_FILE"

if [ -n "$BRANCH" ]; then
    echo "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH +$STAGED ~$MODIFIED"
else
    echo "[$MODEL] 📁 ${DIR##*/}"
fi

Windows 設定

在 Windows 上,Claude Code 透過 Git Bash 執行狀態列命令。您可以從該 shell 呼叫 PowerShell:
{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
  }
}
或直接執行 Bash 指令碼:
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

提示

  • 使用模擬輸入測試echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25}}' | ./statusline.sh
  • 保持輸出簡短:狀態列寬度有限,因此長輸出可能會被截斷或換行不當
  • 快取慢速操作:您的指令碼在活躍工作階段期間頻繁執行,因此 git status 等命令可能會導致延遲。請參閱快取範例以瞭解如何處理此問題。
社群專案如 ccstatuslinestarship-claude 提供具有主題和其他功能的預先建立設定。

疑難排解

狀態列未出現
  • 驗證您的指令碼是否可執行:chmod +x ~/.claude/statusline.sh
  • 檢查您的指令碼是否輸出到 stdout 而不是 stderr
  • 手動執行您的指令碼以驗證它產生輸出
  • 如果 disableAllHooks 在您的設定中設定為 true,狀態列也會被停用。移除此設定或將其設定為 false 以重新啟用。
  • 執行 claude --debug 以記錄工作階段中第一次狀態列呼叫的結束代碼和 stderr
  • 要求 Claude 讀取您的設定檔案並直接執行 statusLine 命令以顯示錯誤
狀態列顯示 -- 或空值
  • 欄位在第一次 API 回應完成之前可能為 null
  • 在您的指令碼中使用後備(例如 jq 中的 // 0)處理 null 值
  • 如果多個訊息後值仍為空,請重新啟動 Claude Code
Context 百分比顯示意外值
  • 使用 used_percentage 以取得準確的 context 狀態,而不是累積總計
  • total_input_tokenstotal_output_tokens 在整個工作階段中累積,可能超過 context window 大小
  • Context 百分比可能與 /context 輸出不同,因為每個計算時間不同
OSC 8 連結不可點擊
  • 驗證您的終端支援 OSC 8 超連結(iTerm2、Kitty、WezTerm)
  • Terminal.app 不支援可點擊連結
  • SSH 和 tmux 工作階段可能根據設定去除 OSC 序列
  • 如果逃逸序列顯示為文字(如 \e]8;;),請使用 printf '%b' 而不是 echo -e 以獲得更可靠的逃逸處理
逃逸序列的顯示故障
  • 複雜的逃逸序列(ANSI 顏色、OSC 8 連結)如果與其他 UI 更新重疊,偶爾會導致輸出損壞
  • 如果您看到損壞的文字,請嘗試簡化您的指令碼為純文字輸出
  • 帶有逃逸碼的多行狀態列比單行純文字更容易出現呈現問題
指令碼錯誤或掛起
  • 以非零代碼結束或不產生輸出的指令碼會導致狀態列變為空白
  • 慢速指令碼會阻止狀態列更新,直到它們完成。保持指令碼快速以避免過時的輸出。
  • 如果在慢速指令碼執行時觸發新的更新,進行中的指令碼會被取消
  • 在設定之前使用模擬輸入獨立測試您的指令碼
通知共享狀態列行
  • 系統通知(如 MCP 伺服器錯誤、自動更新和令牌警告)顯示在與您的狀態列相同行的右側
  • 啟用詳細模式會在此區域新增令牌計數器
  • 在狹窄的終端上,這些通知可能會截斷您的狀態列輸出