教程

Claude Code Status Line 完全指南:自定义状态栏显示 Context 用量、Git 状态与费用追踪

Claude Code Status Line 完全指南:/statusline 自然语言生成脚本、手动 settings.json 配置、stdin JSON 数据结构详解(model/context_window/git/session 字段)、Context 彩色进度条、Git 状态着色、费用时长追踪、多行状态栏实战脚本,以及缓存优化和故障排查。

2026/3/45分钟 阅读ClaudeEagle

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_namestring模型显示名称
model.idstring模型 ID

Context 窗口字段

字段类型说明
context_window.used_tokensint已使用 Token 数
context_window.total_tokensint总 Token 容量
context_window.used_percentagefloat使用百分比(0-100)
context_window.cache_tokensint已缓存 Token 数

工作区

字段类型说明
workspace.current_dirstring当前工作目录
workspace.project_namestring项目名称

会话信息

字段类型说明
session.cost_usdfloat本次会话费用(美元)
session.duration_msint会话持续时间(毫秒)

Git 信息

字段类型说明
git.branchstring当前分支名称
git.has_changesbool是否有未提交改动

实用示例

示例 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 官方文档

相关文章推荐

教程Claude Code 自定义状态栏完整指南:/statusline 命令、JSON 数据字段与多行彩色状态栏实战Claude Code 状态栏完整指南:两种设置方式(/statusline 自然语言描述自动生成 vs 手动 settings.json 配置 type:command)、三步从零构建(脚本/chmod+x/settings.json)、完整 JSON 数据字段(模型/上下文窗口 5 个字段/工作区 Git 5 个字段/会话成本时长/权限模式/Vim 模式)、四个实战示例(颜色进度条 20 块/Git 分支状态颜色/成本时长追踪/多行状态栏)、状态栏工作机制(300ms 防抖/取消机制/不消耗 API Token)和禁用方法。2026/3/9教程Claude Code 键盘快捷键完全指南:自定义快捷键、全部默认键位速查与 keybindings.json 配置Claude Code 键盘快捷键完全指南:/keybindings 命令、keybindings.json 配置格式、全部 18 个 Context 说明(Chat/Global/Autocomplete/Confirmation/Task 等)、所有默认键位速查表(全局/历史/聊天/确认/任务),以及解绑键位的 null 配置和 JSON Schema 编辑器自动补全。2026/3/4教程Claude Code Skills 进阶:动态上下文注入、路径限定激活和 Subagent 集成深度指南Claude Code Skills 三个高级特性深度指南:动态上下文注入(!! 命令预处理原理、内联和多行语法、实战健康检查 Skill 含 6 个命令块、安全注意事项);路径限定自动激活(TypeScript 严格模式/SQL 安全/React 组件三个实战示例);context: fork 在 Subagent 运行(适用场景判断、agent 类型选择);以及三种特性组合的完整 PR 审查 Skill 示例。2026/5/10教程Claude Code Skills 官方完整指南:从入门到高级模式的权威教程Claude Code Skills 官方文档完整中文整理:Skills vs CLAUDE.md 核心区别;目录结构;存储位置和优先级;实时变更检测和 Monorepo 自动发现;完整 Frontmatter 字段参考(20+字段);字符串替换(动态参数);内容类型(参考类 vs 任务类);调用控制表;Skill 内容生命周期(压缩保留机制);三个高级模式(动态注入/路径限定/Subagent运行);以及内置 Bundled Skills 和权限控制方法。2026/5/10教程Claude Code Slack 集成完整指南:团队协作、CI 通知和权限管理Claude Code Slack 集成完整指南:5 大核心功能(频道触发任务/代码问答/CI 通知/PR 审查/Routines 结果推送);安装配置步骤;4 个权限等级(read/write/execute/pr)及频道级配置;人工审批工作流;GitHub Actions + Slack 通知自动化;4 个团队协作场景(新人上手/PM 提需求/频道分工规范/结构化请求模板);以及官方 Slack 集成 vs OpenClaw 方案的对比。2026/5/8教程Claude Code 定时任务完整指南:/schedule、Routines 三种触发方式和 /loop 监控/schedule 命令和 Routines 完整指南:/schedule 创建/查看/运行/编辑/删除定时任务;Routines 三种触发方式(Cron 定时/GitHub 事件/Webhook API /fire 端点);4 个实战 Routine 配置(每日健康检查/PR 自动质量门/每周技术债扫描/CI 失败分析);/loop 会话内定期重复(vs /schedule 的区别对比);Routines 访问权限配置(GitHub/Slack/数据库);以及 Routines + ultrareview/Hooks/Subagents 的组合用法。2026/5/8