- 你想在工作时监控上下文窗口使用情况
- 你需要跟踪会话成本
- 你在多个会话中工作,需要区分它们
- 你希望 git 分支和状态始终可见
esc to interrupt、? for shortcuts 回退和 hold space to speak 语音听写提示。要在对话中出现 ID 时向页脚添加可点击的链接徽章,而无需编写脚本,请改为配置 footerLinksRegexes。
这是一个多行状态行的示例,它在第一行显示 git 信息,在第二行显示颜色编码的上下文栏。

设置状态行
使用/statusline 命令让 Claude Code 为你生成脚本,或手动创建脚本并将其添加到你的设置中。
使用 /statusline 命令
/statusline 命令接受描述你想显示的内容的自然语言指令。Claude Code 在 ~/.claude/ 中生成脚本文件并自动更新你的设置:
手动配置状态行
将statusLine 字段添加到你的用户设置(~/.claude/settings.json,其中 ~ 是你的主目录)或项目设置。将 type 设置为 "command" 并将 command 指向脚本路径或内联 shell 命令。有关创建脚本的完整演练,请参阅逐步构建状态行。
command 字段在 shell 中运行,所以你也可以使用内联命令而不是脚本文件。此示例使用 jq 解析 JSON 输入并显示模型名称和上下文百分比:
padding 字段为状态行内容添加额外的水平间距(以字符为单位)。默认为 0。此填充是在界面的内置间距之外的,所以它控制相对缩进而不是距离终端边缘的绝对距离。
可选的 refreshInterval 字段除了事件驱动的更新外,每 N 秒重新运行一次你的命令。最小值为 1。当你的状态行显示基于时间的数据(如时钟)或后台子代理在主会话空闲时更改 git 状态时,设置此选项。如果不设置,则仅在事件上运行。
可选的 hideVimModeIndicator 字段会抑制提示符下方的内置 -- INSERT -- 文本。当你的脚本自己呈现 vim.mode 时,将此设置为 true,这样模式就不会显示两次。
禁用状态行
运行/statusline 并要求它删除或清除你的状态行(例如,/statusline delete、/statusline clear、/statusline remove it)。你也可以手动从 settings.json 中删除 statusLine 字段。
逐步构建状态行
本演练展示了/statusline 为你设置的内容,通过手动创建显示当前模型、工作目录和上下文窗口使用百分比的状态行。
使用
/statusline和你想要的内容的描述会自动为你配置所有这些。
1
创建一个读取 JSON 并打印输出的脚本
Claude Code 通过 stdin 向你的脚本发送 JSON 数据。此脚本使用
jq,一个你可能需要安装的命令行 JSON 解析器,来提取模型名称、目录和上下文百分比,然后打印格式化的行。将其保存到 ~/.claude/statusline.sh(其中 ~ 是你的主目录,例如 macOS 上的 /Users/username 或 Linux 上的 /home/username):2
使其可执行
将脚本标记为可执行,以便你的 shell 可以运行它:
3
添加到设置
告诉 Claude Code 运行你的脚本作为状态行。将此配置添加到 你的状态行出现在界面的底部。Claude Code 会自动重新加载设置,并在你保存文件后立即运行你的脚本。
~/.claude/settings.json,它将 type 设置为 "command"(意思是”运行此 shell 命令”)并将 command 指向你的脚本:状态栏如何工作
Claude Code 运行您的脚本,通过 stdin 向其传输 JSON 会话数据,并显示脚本打印到 stdout 的任何内容。状态栏在本地运行,不消耗 API token。在某些 UI 交互期间,它会临时隐藏,包括帮助菜单和权限提示。
状态栏何时更新
脚本在会话启动时运行一次,包括恢复会话时。之后,它在以下情况下再次运行:- 新的助手消息到达
/compact完成- 权限模式更改
- Vim 模式切换
- 您在
statusLine设置中更改command - 如果您设置了
refreshInterval,其计时器到期 - 脚本最后接收的数据中的速率限制窗口到达其
resets_at时间 - 脚本最后接收的数据中的预热提示词缓存到达其
expires_at时间
command 本身的更改会跳过防抖:Claude Code 立即运行新命令。如果在脚本仍在运行时触发新的更新,Claude Code 会取消正在进行的脚本。如果您编辑了脚本,更改会在下次更新触发重新运行它时出现。
当主会话空闲时,事件驱动的触发器可能会停止触发,例如当协调器等待后台子代理时。为了在空闲期间保持基于时间或外部来源的片段为最新状态,请设置 refreshInterval,以便同时按固定计时器重新运行命令。
脚本可以输出什么
脚本可以打印的不仅仅是单行纯文本:- 多行:每个
echo或print语句显示为单独的行。请参阅多行示例。 - 颜色:使用 ANSI 转义码,如
\033[32m表示绿色(终端必须支持它们)。请参阅 git 状态示例。 - 链接:使用 OSC 8 转义序列 使文本可点击(macOS 上为 Cmd+click,Windows/Linux 上为 Ctrl+click)。需要支持超链接的终端,如 iTerm2、Kitty 或 WezTerm。请参阅可点击链接示例。
调整输出大小以适应终端
Claude Code 捕获脚本的输出而不是直接将其连接到终端,因此tput cols 和语言级宽度检测无法从脚本内部读取终端大小。请改为读取 COLUMNS 和 LINES 环境变量。Claude Code 在运行脚本之前会将这些变量设置为当前终端尺寸。
可用数据
Claude Code 通过 stdin 向您的脚本发送以下 JSON 字段:完整 JSON schema
完整 JSON schema
您的状态栏命令通过 stdin 接收以下 JSON 结构:可能不存在的字段(不出现在 JSON 中):
session_name:在通过--name或/rename设置了自定义名称时,或者存在 AI 生成的会话标题后出现。默认显示名称(例如my-app-3f)不会填充此字段prompt_id:仅在第一次用户输入之后出现workspace.git_worktree:仅当当前目录位于链接的 git worktree 中时出现workspace.repo:仅在配置了origin远程的 git 仓库中出现effort:仅当当前模型支持推理努力程度参数时出现vim:仅在启用 vim 模式时出现agent:仅在使用--agent标志运行或配置了 Agent 设置时出现pr:仅在为当前分支找到已打开的 PR 或 GitLab merge request 时出现,并在其合并或关闭后移除。pr.review_state和pr.kind可能单独缺失worktree:仅在会话处于 worktree 会话时出现。存在时,对于基于 hook 的 worktree,branch和original_branch也可能不存在rate_limits:仅对 claude.ai Pro、Max 和 Ultra 订阅用户,或在为您设置了支出限额的 Claude apps 网关后方时出现。即便如此,它也仅在会话中第一次 API 响应之后出现。每个窗口(five_hour、seven_day、spend_limit)都可能单独缺失,并且一旦某个窗口的resets_at时间已过,Claude Code 就会移除该窗口。使用jq -r '.rate_limits.five_hour.used_percentage // empty'可以妥善处理字段缺失的情况。prompt_cache:在主对话的第一次 API 响应之后出现。请参阅提示缓存字段
null 的字段:context_window.current_usage:在会话中第一次 API 调用之前为null,在/compact之后也会再次为null,直到下一次 API 调用重新填充它context_window.used_percentage、context_window.remaining_percentage:在会话早期可能为null
上下文窗口字段
context_window 对象描述来自最近一次 API 响应的实时上下文窗口。
- 合计总数(
total_input_tokens、total_output_tokens):当前上下文窗口中的 token。total_input_tokens是input_tokens、cache_creation_input_tokens和cache_read_input_tokens之和;total_output_tokens是最近一次响应的输出 token。在第一次 API 响应之前,两者均为0。 - 按组成部分的用量(
current_usage):按类别拆分的相同 token 数。当您需要将缓存命中与新输入分开时,请使用此项。
current_usage 对象包含:
input_tokens:当前上下文中的输入 tokenoutput_tokens:生成的输出 tokencache_creation_input_tokens:写入缓存的 tokencache_read_input_tokens:从缓存读取的 token
used_percentage 字段仅根据输入 token 计算:input_tokens + cache_creation_input_tokens + cache_read_input_tokens。它不包括 output_tokens。
如果您根据 current_usage 手动计算上下文百分比,请使用相同的仅输入公式,以与 used_percentage 保持一致。
current_usage 对象在会话中第一次 API 调用之前为 null,并且在 /compact 之后会立即再次变为 null,直到下一次 API 调用重新填充它。
支出限额字段
在设有支出限额的 Claude apps 网关后方时,rate_limits.spend_limit 对象描述适用于您的支出限额。它在会话的第一次 API 响应之后出现,需要 Claude Code v2.1.251 或更高版本。您的脚本会按不同的时间安排接收其各个字段:
used_percentage和resets_at:随每次响应一起提供,因此只要存在spend_limit,它们就存在。used_percentage的范围为 0 到 100,超出限额后会高于 100;resets_at是限额周期重置的时间(Unix 纪元秒)。used_usd、limit_usd和period:以美元计的迄今预估支出和限额,以及限额所覆盖的周期,取值为daily、weekly或monthly之一。网关根据 token 数计算used_usd,因此它是一个估算值,而不是计费金额。Claude Code 通过单独的请求从网关读取这些字段,在您发送请求期间大约每五分钟读取一次。美元金额可能比used_percentage滞后约五分钟,因此两者可能短暂不一致。Claude Code 和网关均需 v2.1.284 或更高版本。
spend_limit,也应将 used_usd、limit_usd 和 period 视为可选字段,因为您的脚本会先于它们收到百分比。请在脚本中为每个字段提供备用值进行读取,例如 jq -r '.rate_limits.spend_limit.used_usd // empty'。在 Claude Code v2.1.295 之前,如果您设置了 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC,这些字段会一直不存在,因为该设置会关闭那个请求。
提示缓存字段
prompt_cache 对象汇总了会话主对话使用提示缓存的情况。Claude Code 根据 API 响应中的缓存 token 数计算该对象,因此它适用于所有提供商。
该对象在主对话的第一次 API 响应之后出现。Claude Code 不会将子代理请求计入这些统计信息。需要 Claude Code v2.1.251 或更高版本。
下表列出了每个字段及其含义。时间戳为 Unix 纪元秒,与 rate_limits.*.resets_at 的单位相同。简短的状态栏通常只显示其中一两个字段;warm 和 hit_ratio 最直接地概括了缓存状态。
Claude Code 在终端中的
/usage 命令的 Prompt cache (main) 行上显示相同的统计信息。
最后一次未命中原因
last_miss_cause 对象报告 Claude Code 判定的最近一次未命中的可能原因。其 causes 数组包含一个或多个原因名称,例如 tools_changed、system_prompt_changed、ttl_expired_5m 或 likely_server_side。在会话第一次未命中之前,该对象为 null;每当 Claude Code 无法确定最近一次未命中的原因时,也会再次为 null。需要 Claude Code v2.1.260 或更高版本。
有两种原因会向该对象添加计数:
tools_added和tools_removed:与tools_changed一起出现,表示向请求中添加或从请求中移除的工具数量system_char_delta:与system_prompt_changed一起出现,表示系统提示词长度的变化,以字符为单位
示例
这些示例展示了常见的状态行模式。要使用任何示例:- 将脚本保存到文件,如
~/.claude/statusline.sh(或.py/.js) - 使其可执行:
chmod +x ~/.claude/statusline.sh - 将路径添加到你的设置
jq 来解析 JSON。Python 和 Node.js 具有内置的 JSON 解析。
上下文窗口使用情况
显示当前模型和上下文窗口使用情况,带有可视进度条。每个脚本从 stdin 读取 JSON,提取used_percentage 字段,并构建一个 10 字符的栏,其中填充的块(▓)代表使用情况:

Git 状态与颜色
显示 git 分支,带有暂存和修改文件的颜色编码指示器。此脚本使用ANSI 转义码表示终端颜色:\033[32m 是绿色,\033[33m 是黄色,\033[0m 重置为默认值。

成本和持续时间跟踪
跟踪你的会话的 API 成本和经过的时间。cost.total_cost_usd 字段累积当前会话中所有 API 调用的估计成本。cost.total_duration_ms 字段测量自会话开始以来的总经过时间,而 cost.total_api_duration_ms 仅跟踪等待 API 响应的时间。
每个脚本将成本格式化为货币并将毫秒转换为分钟和秒:

显示多行
你的脚本可以输出多行来创建更丰富的显示。
print 或 echo 语句创建单独的行:
可点击链接
此示例创建指向你的 GitHub 存储库的可点击链接。按住 Cmd(macOS)或 Ctrl(Windows/Linux)并单击以在浏览器中打开链接。
printf '%b',它比 echo -e 更可靠地跨不同 shell 解释反斜杠转义:
速率限制使用情况
在状态栏中显示 claude.ai 订阅速率限制使用情况,或您相对于 Claude 应用网关支出限制的支出。对于订阅者,rate_limits 对象可以包含一个滚动的 five_hour 窗口和一个每周的 seven_day 窗口。每个窗口提供 used_percentage(从 0 到 100)和 resets_at(窗口重置时的 Unix 纪元秒数)。在网关后面时,请读取 spend_limit 对象,详见支出限制字段。
rate_limits 对象仅对 claude.ai Pro、Max 和 Ultra 订阅者或具有支出限制的 Claude 应用网关后面的用户出现,并且仅在第一次 API 响应后出现。每个脚本都会优雅地处理缺失的字段,并且在网关后面时打印 spend: $314.12 / $500,或在美元字段缺失时打印 spend: 63%:
缓存昂贵的操作
你的状态行脚本在活跃会话期间频繁运行。像git status 或 git diff 这样的命令可能很慢,特别是在大型存储库中。此示例将 git 信息缓存到临时文件,并仅每 5 秒刷新一次。
缓存文件名需要在会话内的状态行调用中保持稳定,但在会话之间是唯一的,以便不同存储库中的并发会话不会读取彼此的缓存 git 状态。基于进程的标识符如 $$、os.getpid() 或 process.pid 在每次调用时都会改变,会破坏缓存。改用 JSON 输入中的 session_id:它在会话的生命周期内是稳定的,并且对每个会话是唯一的。
每个脚本在运行 git 命令之前检查缓存文件是否缺失或早于 5 秒:
Windows 配置
在 Windows 上,Claude Code 通过 Git Bash 运行状态行命令(如果已安装 Git Bash),或在没有 Git Bash 时通过 PowerShell 运行。 Git Bash 将未引用的反斜杠视为转义字符,因此 Windows 风格的路径(如C:\Users\username\script.mjs)到达脚本运行器时会删除其分隔符,命令会失败而没有可见的错误。在 command 字符串中使用正斜杠编写文件路径,如下面的示例所示。~ 快捷方式也有效,并扩展到你的 Windows 主目录。
要将 PowerShell 脚本作为状态行运行,请通过 powershell 调用它。无论 Claude Code 通过 Git Bash 还是 PowerShell 路由命令,这都有效:
提示
- 使用模拟输入测试:
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh - 保持输出简短:状态栏的宽度有限,所以长输出可能会被截断或换行不当
- 缓存慢速操作:你的脚本在活跃会话期间频繁运行,所以像
git status这样的命令可能会导致延迟。请参阅缓存示例了解如何处理这个问题。
故障排除
如果状态栏为空白,请先查看状态栏未出现。尚未信任的文件夹以及运行失败的脚本也会导致状态栏为空白,具体请参见需要工作区信任和脚本错误或挂起。状态栏未出现
如果您已配置状态栏,但界面底部没有任何显示,请逐项进行以下检查:- 验证您的脚本是可执行的:
chmod +x ~/.claude/statusline.sh - 检查您的脚本输出到 stdout,而不是 stderr
- 手动运行您的脚本以验证它产生输出
- 在安装了 Git Bash 的 Windows 上,
command路径中的反斜杠可能在脚本运行前被当作转义字符消耗。请在路径中使用正斜杠。参见 Windows 配置。 - 如果在应用设置优先级后
disableAllHooks在托管设置之外为true,Claude Code 仅运行来自托管设置的statusLine,如果没有托管statusLine,状态栏将被禁用。删除该设置,或在设置它的文件中将其设置为false以重新启用。参见disableAllHooks。 - 如果您的组织在托管设置中设置了
allowManagedHooksOnly,您的自定义状态栏会无警告地消失:您只能从那些托管设置中的statusLine值获得状态栏。参见在allowManagedHooksOnly下运行的内容了解完整行为,并询问您的管理员此设置是否适用于您。 - 运行
claude --debug以在每次状态栏调用时记录您的脚本的 stderr,以及在会话中第一次调用时的退出码 - 要求 Claude 读取您的设置文件并直接执行
statusLine命令以显示错误
状态栏显示 -- 或空值
在第一次 API 响应完成之前,字段可能为 null,因此请在脚本中使用回退处理 null 值,如 jq 中的 // 0。如果值在多条消息后仍然为空,请重新启动 Claude Code。
上下文百分比显示意外值
状态栏报告来自最后一次 API 响应的计数,而/context 添加了自该响应以来新增消息的估计值,因此在下一次响应之前,/context 的读数可能更高。使用 used_percentage 获得最简单的准确上下文状态。有关 used_percentage 背后的计算公式,请参见上下文窗口字段。
OSC 8 链接不可点击
链接是否可点击取决于您的终端、Claude Code 是否在其中检测到超链接支持、SSH 或 tmux 是否剥离了转义序列,以及您的脚本如何打印它:- 验证您的终端支持 OSC 8 超链接(iTerm2、Kitty、WezTerm)
- Terminal.app 不支持可点击链接
-
如果链接文本出现但不可点击,Claude Code 可能未检测到您的终端中的超链接支持。在启动 Claude Code 之前设置
FORCE_HYPERLINK环境变量以覆盖检测:在 PowerShell 中,首先在当前会话中设置变量: - SSH 和 tmux 会话可能根据配置剥离 OSC 序列
-
如果转义序列显示为文字文本,如
\e]8;;,请使用printf '%b'而不是echo -e以获得更可靠的转义处理
转义序列显示故障
复杂的转义序列(ANSI 颜色、OSC 8 链接)如果与其他 UI 更新重叠,偶尔会导致输出混乱。带有转义码的多行状态栏比单行纯文本更容易出现渲染问题。 如果您看到损坏的文本,请尝试将脚本简化为纯文本输出。需要工作区信任
在您接受工作区信任对话框之前,状态栏会保持空白。因为statusLine 执行 shell 命令,Claude Code 在与设置文件中的 hook 相同的工作区信任规则下运行它。接受该文件夹的对话框,或接受其信任扩展到它的父目录,就足够了。
在此之前,claude --debug 会记录 Status line command skipped: workspace trust not accepted。重新启动 Claude Code 并接受信任对话框以启用它。
脚本错误或挂起
Claude Code 仅在脚本以代码 0 退出后才显示其输出:- 以非零代码退出或不产生输出的脚本会导致状态栏变为空白
- 慢速脚本会阻止状态栏更新,直到它们完成。保持脚本快速以避免陈旧输出。
- 如果在慢速脚本运行时触发新的更新,正在进行的脚本会被取消
- 在配置之前使用模拟输入独立测试您的脚本
通知与状态栏共享同一行
在全屏渲染之外,Claude Code 在与您的状态栏相同的行上显示通知。在全屏渲染中,Claude Code 会为通知提供单独的一行。- 系统通知,如 MCP 服务器错误和自动更新,显示在该行的右侧。临时通知,如上下文不足警告,也会在此区域轮流显示。
- 启用详细模式会向此区域添加 token 计数器,显示的是最后一次 API 响应所报告的上下文大小,而不是旋转指示器旁边的每轮计数
- 在窄终端上,这些通知可能会截断您的状态栏输出