Claude Code 的 Status Line（状态栏）是底部的自定义信息条，运行你配置的任意 Shell 脚本，接收 JSON 会话数据后输出格式化信息。常用于实时监控 Context 窗口用量、跟踪会话费用和查看 Git 状态。
快速启用：/statusline 命令
最简单的方式——用自然语言告诉 Claude 你想显示什么：
bash
/statusline show model name and context percentage with a progress bar
/statusline show git branch, cost and context usage
/statusline 显示模型名称、当前目录和 Context 使用百分比Claude Code 会自动在 ~/.claude/ 生成脚本文件，并更新 settings.json。
关闭状态栏：
bash
/statusline delete
/statusline clear
/statusline remove it手动配置
在 ~/.claude/settings.json 中添加 statusLine 字段：
json
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2
}
}也可以直接内联命令（需要安装 jq）：
json
{
"statusLine": {
"type": "command",
"command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
}
}padding 字段控制额外水平间距（字符数），默认 0。
从零构建一个状态栏脚本
Step 1：了解输入数据格式
Claude Code 将 JSON 数据通过 stdin 传入你的脚本，结构如下：
json
{
"model": {
"display_name": "claude-opus-4-6"
},
"workspace": {
"current_dir": "/Users/user/myproject"
},
"context_window": {
"used_tokens": 45230,
"total_tokens": 200000,
"used_percentage": 22.6
},
"session": {
"cost_usd": 0.043,
"duration_ms": 125000
},
"git": {
"branch": "main",
"has_changes": true
}
}Step 2：创建基础脚本
bash
#!/bin/bash
# ~/.claude/statusline.sh
input=$(cat)
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)
# ${DIR##*/} 只取文件夹名称
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"保存后设为可执行：
bash
chmod +x ~/.claude/statusline.sh可用数据字段
模型信息
| 字段 | 类型 | 说明 |
|---|---|---|
model.display_name | string | 模型显示名称 |
model.id | string | 模型 ID |
Context 窗口字段
| 字段 | 类型 | 说明 |
|---|---|---|
context_window.used_tokens | int | 已使用 Token 数 |
context_window.total_tokens | int | 总 Token 容量 |
context_window.used_percentage | float | 使用百分比（0-100） |
context_window.cache_tokens | int | 已缓存 Token 数 |
工作区
| 字段 | 类型 | 说明 |
|---|---|---|
workspace.current_dir | string | 当前工作目录 |
workspace.project_name | string | 项目名称 |
会话信息
| 字段 | 类型 | 说明 |
|---|---|---|
session.cost_usd | float | 本次会话费用（美元） |
session.duration_ms | int | 会话持续时间（毫秒） |
Git 信息
| 字段 | 类型 | 说明 |
|---|---|---|
git.branch | string | 当前分支名称 |
git.has_changes | bool | 是否有未提交改动 |
实用示例
示例 1：Context 进度条
bash
#!/bin/bash
input=$(cat)
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
# 生成 10 格进度条
FILLED=$(( PCT * 10 / 100 ))
EMPTY=$(( 10 - FILLED ))
BAR=$(printf '%0.s█' $(seq 1 $FILLED))$(printf '%0.s░' $(seq 1 $EMPTY))
# 根据用量着色
if [ "$PCT" -gt 80 ]; then
COLOR="\033[31m" # 红色
elif [ "$PCT" -gt 60 ]; then
COLOR="\033[33m" # 黄色
else
COLOR="\033[32m" # 绿色
fi
echo -e "${COLOR}${BAR}\033[0m ${PCT}% context"示例 2：Git 状态 + 颜色
bash
#!/bin/bash
input=$(cat)
BRANCH=$(echo "$input" | jq -r '.git.branch // "no-git"')
CHANGES=$(echo "$input" | jq -r '.git.has_changes')
if [ "$CHANGES" = "true" ]; then
GIT_STATUS="\033[33m${BRANCH}*\033[0m"
else
GIT_STATUS="\033[32m${BRANCH}\033[0m"
fi
echo -e "🌿 ${GIT_STATUS}"示例 3：费用与时长追踪
bash
#!/bin/bash
input=$(cat)
COST=$(echo "$input" | jq -r '.session.cost_usd // 0')
DURATION_MS=$(echo "$input" | jq -r '.session.duration_ms // 0')
MINUTES=$(( DURATION_MS / 60000 ))
echo "💰 \$${COST} | ⏱ ${MINUTES}min"示例 4：多行状态栏（终极版）
bash
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
BRANCH=$(echo "$input" | jq -r '.git.branch // ""')
CHANGES=$(echo "$input" | jq -r '.git.has_changes')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
COST=$(echo "$input" | jq -r '.session.cost_usd // 0')
# 第一行：模型 + 目录 + Git
GIT_PART=""
if [ -n "$BRANCH" ]; then
[ "$CHANGES" = "true" ] && GIT_PART=" 🌿 ${BRANCH}*" || GIT_PART=" 🌿 ${BRANCH}"
fi
echo "[${MODEL}] 📁 ${DIR##*/}${GIT_PART}"
# 第二行：Context 进度条 + 费用
FILLED=$(( PCT * 20 / 100 ))
EMPTY=$(( 20 - FILLED ))
BAR=$(printf '%0.s█' $(seq 1 $FILLED 2>/dev/null))$(printf '%0.s░' $(seq 1 $EMPTY 2>/dev/null))
echo "${BAR} ${PCT}% | 💰 \$${COST}"性能优化：缓存昂贵操作
状态栏脚本会频繁执行，避免在脚本中运行慢速命令（如 git status、网络请求）。使用文件缓存：
bash
CACHE_FILE="/tmp/claude-statusline-cache"
CACHE_TTL=10 # 秒
# 检查缓存是否还有效
if [ -f "$CACHE_FILE" ]; then
AGE=$(( $(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || echo 0) ))
if [ "$AGE" -lt "$CACHE_TTL" ]; then
cat "$CACHE_FILE"
exit 0
fi
fi
# 重新计算并缓存
RESULT="...你的慢操作..."
echo "$RESULT" | tee "$CACHE_FILE"故障排查
状态栏不显示？
- 检查脚本是否有可执行权限：
chmod +x ~/.claude/statusline.sh - 确认路径正确（
~是字面 home 目录，不是环境变量） - 测试脚本：
echo '{}' | ~/.claude/statusline.sh
显示乱码？
- 确认终端支持 UTF-8 和 Emoji
- 尝试去掉 Emoji 改用 ASCII 符号
数据字段为空（null）？
- 使用
// "默认值"语法提供回退值 - 确认字段名称拼写正确（区分大小写）
原文：Customize your status line - Claude Code Docs | 来源：Anthropic 官方文档