状态栏（Status Line）是 Claude Code 终端底部可自定义的信息栏，运行任意 Shell 脚本，接收 JSON 会话数据，显示上下文用量、成本、Git 状态或任何信息。
快速设置
方式一：/statusline 自然语言描述（最快）
/statusline show model name and context percentage with a progress bar
Claude Code 自动生成脚本文件（保存到 ~/.claude/），并更新 settings.json 配置。
方式二：手动配置 settings.json
json
// ~/.claude/settings.json
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2
}
}内联命令（无需脚本文件）：
json
{
"statusLine": {
"type": "command",
"command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
}
}padding：额外水平空白字符数（默认 0）。
从零构建状态栏（3 步）
第一步：创建脚本
bash
#!/bin/bash
# ~/.claude/statusline.sh
input=$(cat) # 读取 Claude Code 传来的 JSON
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"第二步：赋予执行权限
bash
chmod +x ~/.claude/statusline.sh第三步：写入 settings.json
json
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}可用的 JSON 数据字段
模型信息
| 字段 | 类型 | 说明 |
|---|---|---|
.model.display_name | string | 模型显示名（如 "Claude Sonnet 4.6"） |
.model.id | string | 模型 ID（如 claude-sonnet-4-6） |
上下文窗口
| 字段 | 类型 | 说明 |
|---|---|---|
.context_window.used_tokens | number | 已使用 Token 数 |
.context_window.total_tokens | number | 总 Token 容量 |
.context_window.used_percentage | number | 使用百分比（0–100） |
.context_window.cache_read_tokens | number | 缓存命中读取的 Token 数 |
.context_window.cache_creation_tokens | number | 创建缓存的 Token 数 |
工作区
| 字段 | 类型 | 说明 |
|---|---|---|
.workspace.current_dir | string | 当前工作目录绝对路径 |
.workspace.git_branch | string | 当前 Git 分支名 |
.workspace.git_status | string | Git 状态（clean/modified/untracked/staged/conflict） |
.workspace.git_ahead | number | 领先远程的 commit 数 |
.workspace.git_behind | number | 落后远程的 commit 数 |
会话与成本
| 字段 | 类型 | 说明 |
|---|---|---|
.session.id | string | 会话 UUID |
.session.name | string | 会话名称（如果已重命名） |
.session.duration_seconds | number | 会话已运行秒数 |
.session.cost_usd | number | 本次会话 API 成本（美元） |
权限与模式
| 字段 | 类型 | 说明 |
|---|---|---|
.permission_mode | string | 当前权限模式（default/acceptEdits/plan 等） |
.vim_mode | string | Vim 模式状态（"off"/"INSERT"/"NORMAL"） |
实战示例
1. 上下文进度条（带颜色）
bash
#!/bin/bash
input=$(cat)
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
FILLED=$((PCT / 5)) # 每 5% 一个块
EMPTY=$((20 - FILLED))
# 颜色：绿→黄→红
if [ "$PCT" -lt 50 ]; then COLOR="\033[32m" # 绿
elif [ "$PCT" -lt 80 ]; then COLOR="\033[33m" # 黄
else COLOR="\033[31m"; fi # 红
RESET="\033[0m"
BAR="$(printf '%0.s█' $(seq 1 $FILLED))$(printf '%0.s░' $(seq 1 $EMPTY))"
echo -e "${COLOR}[${BAR}] ${PCT}%${RESET}"2. Git 状态（带颜色）
bash
#!/bin/bash
input=$(cat)
BRANCH=$(echo "$input" | jq -r '.workspace.git_branch // ""')
STATUS=$(echo "$input" | jq -r '.workspace.git_status // "clean"')
AHEAD=$(echo "$input" | jq -r '.workspace.git_ahead // 0')
case "$STATUS" in
clean) COLOR="\033[32m" ;; # 绿
modified) COLOR="\033[33m" ;; # 黄
staged) COLOR="\033[34m" ;; # 蓝
conflict) COLOR="\033[31m" ;; # 红
*) COLOR="\033[37m" ;; # 默认
esac
RESET="\033[0m"
AHEAD_STR=$([ "$AHEAD" -gt 0 ] && echo " ↑${AHEAD}" || echo "")
echo -e "${COLOR}⎇ ${BRANCH}${AHEAD_STR}${RESET}"3. 成本和时长追踪
bash
#!/bin/bash
input=$(cat)
COST=$(echo "$input" | jq -r '.session.cost_usd // 0')
DUR=$(echo "$input" | jq -r '.session.duration_seconds // 0')
MINS=$((DUR / 60))
printf '💰 $%.4f | ⏱ %dm\n' "$COST" "$MINS"4. 多行状态栏
Shell 脚本每次 echo 输出一行，Claude Code 自动显示为多行：
bash
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
BRANCH=$(echo "$input" | jq -r '.workspace.git_branch // "no-git"')
COST=$(echo "$input" | jq -r '.session.cost_usd // 0')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
# 第一行：模型 + Git
echo "🤖 $MODEL | ⎇ $BRANCH"
# 第二行：成本 + 上下文
printf '💰 $%.4f | 📊 %d%% context\n' "$COST" "$PCT"状态栏工作机制
- 更新时机：每次 Claude 新消息后、权限模式变更时、Vim 模式切换时
- 防抖：300ms 防抖（快速变化合并为一次执行）
- 取消：新更新触发时，正在运行的脚本被取消
- 性能：状态栏本地运行，不消耗 API Token
- 隐藏：自动补全菜单、帮助菜单、权限提示期间临时隐藏
禁用状态栏
/statusline remove
/statusline clear
或手动删除 settings.json 中的 statusLine 字段。
原文：Customize your status line - Claude Code Docs | 来源：Anthropic 官方文档