Claude Code 自定义状态栏

这篇适合谁、读完能做到什么

如果你每天都在用 Claude Code，想让终端底部一直能看到模型、当前目录、上下文用量或者会话费用，这篇适合你。读完你能写出一个最小的状态栏脚本，接到 Claude Code 的设置里，知道能显示哪些数据，也知道状态栏空白时该从哪里查。^[1]

状态栏是什么，和底栏有什么关系

状态栏是 Claude Code 界面底部的一条可定制的栏，它会运行你指定的 shell 脚本。Claude Code 通过标准输入（stdin）把会话数据以 JSON 的形式交给脚本，脚本打印到标准输出（stdout）的内容就显示在这一栏里。^[1]

状态栏占一行，位于内置底栏徽章的上方，不会替换这些徽章。不过配置了自定义状态栏之后，底栏的大部分键盘提示会隐藏，包括 esc to interrupt。^[1]

准备

需要先装好 Claude Code。示例脚本用 jq 解析 JSON，jq 是一个命令行工具，可能需要自己安装。如果你更习惯 Python 或 Node.js，它们自带 JSON 解析，不需要额外依赖。^[1]

Windows 用户写 command 时要注意路径的写法，下面「常见问题」里有说明。

上手步骤

让 Claude Code 代写。在会话里输入 /statusline 加上你想要的效果，例如：

/statusline show model name and context percentage with a progress bar

它会在 ~/.claude/ 下生成脚本文件，并自动更新设置。过程中如果弹出文件修改的确认，批准即可。^[1]

或者自己写。把下面的脚本保存为 ~/.claude/statusline.sh。它从 stdin 读入 JSON，用 jq 取出模型名、目录和上下文百分比，然后打印成一行。^[1]

#!/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"

加上可执行权限：

chmod +x ~/.claude/statusline.sh

在 ~/.claude/settings.json 里告诉 Claude Code 运行这个脚本：

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

Claude Code 会自动重新加载设置，你保存文件后脚本马上就会运行。^[1]

手动配置时，还可以加上可选的 padding 字段，给状态栏内容增加水平间距（单位是字符），默认值是 0。这个间距叠加在界面自带的间距之上，所以它调的是相对缩进，不是离终端边缘的绝对距离。^[1]

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}

如果想让 command 直接写成一行命令而不是脚本文件，也可以用 jq。下面这个例子同样读取模型名和上下文百分比：

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

什么时候刷新

脚本在会话开始或恢复时运行一次。之后，每当出现新的助手消息、/compact 结束、权限模式变化、Vim 模式切换，或者你修改了 command 设置，它都会再运行一次。Claude Code 会把 300 毫秒内的连续变化合并成一次运行；如果脚本还没跑完又来了新的触发，正在运行的那次会被取消。^[1]

要显示时钟之类随时间变化的内容，可以设置 refreshInterval，单位是秒，最小值为 1。主会话闲置时（比如它在等后台子 agent），事件触发可能停下来，这个定时器能让数据保持更新。^[1]

状态栏在本地运行，不消耗 API token。帮助菜单和权限确认弹窗出现时，它会暂时隐藏。^[1]

脚本能拿到哪些数据

stdin 里的 JSON 包含模型（model.display_name）、当前目录（workspace.current_dir）、上下文用量（context_window.used_percentage）、会话费用（cost.total_cost_usd）、会话时长（cost.total_duration_ms）、会话 ID 和对话记录文件的路径（transcript_path）等字段。^[1]

used_percentage 只按输入 token 计算，也就是输入加上缓存写入和缓存读取，不含输出 token。如果你想从 current_usage 自己算百分比，要用同样的公式，否则和状态栏显示的数对不上。^[1]

/context 显示的数字有时比状态栏高。原因是状态栏用的是上一次 API 响应的统计，而 /context 还会加上那次响应之后新增消息的估算，所以要等下一次响应之后两者才会一致。^[1]

rate_limits 只对 claude.ai 的 Pro、Max、Ultra 订阅用户出现，而且要等会话里第一次 API 响应之后才有。5 小时和 7 天这两个窗口可能分别缺失，脚本里要用默认值处理，例如 jq -r '.rate_limits.five_hour.used_percentage // empty'。^[1]

prompt_cache 里的 warm、ttl、hit_ratio 等字段，同样在主对话第一次 API 响应之后才出现。子 agent 的请求不计入这些统计。^[1]

输出样式和链接

脚本里每个 echo 或 print 就是一行，所以可以输出多行。终端支持的话，ANSI 颜色代码也能用，例如 \033[32m 表示绿色。^[1]

可点击的链接用 OSC 8 转义序列实现，需要 iTerm2、Kitty 或 WezTerm 这类终端。Terminal.app 不支持可点击链接。^[1]

写脚本的几点建议

脚本要快。慢脚本会阻塞状态栏的更新，而且如果新的更新在它运行期间到来，正在运行的那次会被取消，所以耗时的操作要尽量少。^[1] 写好之后，先用模拟的 JSON 输入单独运行一遍，确认它能输出内容，再接入设置。^[1] 脚本以非零状态码退出，或者没有任何输出，状态栏就会变空。^[1]

需要显示时钟这类随时间变化的值时，记得设置 refreshInterval；只读事件触发的话，状态栏只会在上面列出的几个时机更新。^[1]

常见问题

状态栏完全空白。 先检查脚本有没有执行权限，是否输出到了 stdout，以及能不能在命令行里手动运行。脚本以非零状态码退出或者没有输出时，状态栏会变空。另外，没有接受该文件夹的工作区信任对话框之前，状态栏也是空白的，因为 statusLine 会执行 shell 命令。^[1]
排查脚本报错。 运行 claude --debug，每次调用状态栏时都会记录脚本的 stderr；会话里第一次调用时还会记录退出码。^[1]
脚本要快。 慢脚本会阻塞状态栏的更新。在接入设置之前，先用模拟的输入单独测试脚本。^[1]
终端宽度读不到。 脚本的输出被 Claude Code 捕获，所以 tput cols 读不到终端宽度。要读 COLUMNS 和 LINES 这两个环境变量，Claude Code 在运行脚本前会设置它们。^[1]
Windows 路径。 Git Bash 会把路径里没有加引号的反斜杠当作转义字符，导致命令失败，而且不报错。command 里的路径要用正斜杠。PowerShell 脚本可以这样调用：powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1。^[1]