教程

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 Remote Control 使用指南：手机和浏览器远程继续本地会话Claude Code Remote Control 让你在手机、平板或浏览器中继续本地 Claude Code 会话。代码仍在本机执行，web/mobile 只是连接窗口，可访问本地文件、MCP servers 和项目配置。2026/6/8教程Claude Code Routines 指南：定时、API 和 GitHub 事件触发的云端自动化Claude Code Routines 让 Claude Code 在 Anthropic 管理的云端基础设施上自动运行：可按计划执行、由 HTTP API 触发，或响应 GitHub PR/release 等事件。2026/6/8教程Claude Code Agent Teams 使用指南：多 Claude 会话协作、共享任务列表和直接通信Claude Code Agent Teams 适合需要多个 Claude Code 会话并行探索、互相挑战和协调的复杂任务。它不同于 subagents：teammates 有独立上下文、共享任务列表，并能直接通信。2026/6/8教程Claude Code Dynamic Workflows 完整指南：用脚本编排上百个 SubagentsClaude Code Dynamic Workflows 让编排逻辑从上下文窗口迁移到 JavaScript 脚本，适合代码库审计、500 文件迁移、多源交叉验证研究和可重复质量检查。2026/6/8