跳转到主要内容
状态行是 Claude Code 底部的可自定义栏,可以运行你配置的任何 shell 脚本。它通过 stdin 接收 JSON 会话数据,并显示你的脚本打印的任何内容,为你提供一个持久的、一目了然的上下文使用情况、成本、git 状态或任何其他你想跟踪的内容的视图。 状态行在以下情况下很有用:
  • 你想在工作时监控上下文窗口使用情况
  • 你需要跟踪会话成本
  • 你在多个会话中工作,需要区分它们
  • 你希望 git 分支和状态始终可见
状态行在其自己的行中呈现,位于内置页脚徽章上方,不会替换它们。配置自定义状态行后,Claude Code 会停止显示页脚中的大多数键盘提示,包括 esc to interrupt、? for shortcuts 回退和 hold space to speak 语音听写提示。要在对话中出现 ID 时向页脚添加可点击的链接徽章,而无需编写脚本,请改为配置 footerLinksRegexes。 这是一个多行状态行的示例,它在第一行显示 git 信息,在第二行显示颜色编码的上下文栏。
一个多行状态行,显示第一行上的模型名称、目录、git 分支,第二行上的上下文使用进度条、成本和持续时间
本页面介绍了设置基本状态行,解释了数据如何从 Claude Code 流向你的脚本,列出了你可以显示的所有字段,并提供了常见模式的现成示例,如 git 状态、成本跟踪和进度条。

设置状态行

使用/statusline 命令让 Claude Code 为你生成脚本,或手动创建脚本并将其添加到你的设置中。

使用 /statusline 命令

/statusline 命令接受描述你想显示的内容的自然语言指令。Claude Code 在 ~/.claude/ 中生成脚本文件并自动更新你的设置:
如果 Claude Code 在设置过程中要求权限,请批准文件编辑提示。

手动配置状态行

将 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和你想要的内容的描述会自动为你配置所有这些。
这些示例使用 Bash 脚本,在 macOS 和 Linux 上工作。在 Windows 上,请参阅Windows 配置了解 PowerShell 和 Git Bash 示例。
一个状态行,显示模型名称、目录和上下文百分比
1

创建一个读取 JSON 并打印输出的脚本

Claude Code 通过 stdin 向你的脚本发送 JSON 数据。此脚本使用 jq,一个你可能需要安装的命令行 JSON 解析器,来提取模型名称、目录和上下文百分比,然后打印格式化的行。将其保存到 ~/.claude/statusline.sh(其中 ~ 是你的主目录,例如 macOS 上的 /Users/username 或 Linux 上的 /home/username):
2

使其可执行

将脚本标记为可执行,以便你的 shell 可以运行它:
3

添加到设置

告诉 Claude Code 运行你的脚本作为状态行。将此配置添加到 ~/.claude/settings.json,它将 type 设置为 "command"(意思是”运行此 shell 命令”)并将 command 指向你的脚本:
你的状态行出现在界面的底部。Claude Code 会自动重新加载设置,并在你保存文件后立即运行你的脚本。

状态栏如何工作

Claude Code 运行您的脚本,通过 stdin 向其传输 JSON 会话数据,并显示脚本打印到 stdout 的任何内容。
状态栏在本地运行,不消耗 API token。在某些 UI 交互期间,它会临时隐藏,包括帮助菜单和权限提示。

状态栏何时更新

脚本在会话启动时运行一次,包括恢复会话时。之后,它在以下情况下再次运行:
  • 新的助手消息到达
  • /compact 完成
  • 权限模式更改
  • Vim 模式切换
  • 您在 statusLine 设置中更改 command
  • 如果您设置了 refreshInterval,其计时器到期
  • 脚本最后接收的数据中的速率限制窗口到达其 resets_at 时间
  • 脚本最后接收的数据中的预热提示词缓存到达其 expires_at 时间
Claude Code 以 300ms 对更新进行防抖,因此快速更改会批处理在一起,脚本在更改停止后运行一次。对 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 字段:
您的状态栏命令通过 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
在脚本中,请使用条件访问处理缺失字段,并使用备用默认值处理 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:当前上下文中的输入 token
  • output_tokens:生成的输出 token
  • cache_creation_input_tokens:写入缓存的 token
  • cache_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 一起出现,表示系统提示词长度的变化,以字符为单位

示例

这些示例展示了常见的状态行模式。要使用任何示例:
  1. 将脚本保存到文件,如 ~/.claude/statusline.sh(或 .py/.js)
  2. 使其可执行:chmod +x ~/.claude/statusline.sh
  3. 将路径添加到你的设置
Bash 示例使用 jq 来解析 JSON。Python 和 Node.js 具有内置的 JSON 解析。

上下文窗口使用情况

显示当前模型和上下文窗口使用情况,带有可视进度条。每个脚本从 stdin 读取 JSON,提取 used_percentage 字段,并构建一个 10 字符的栏,其中填充的块(▓)代表使用情况:
一个状态行,显示模型名称和带有百分比的进度条

Git 状态与颜色

显示 git 分支,带有暂存和修改文件的颜色编码指示器。此脚本使用ANSI 转义码表示终端颜色:\033[32m 是绿色,\033[33m 是黄色,\033[0m 重置为默认值。
一个状态行,显示模型、目录、git 分支和暂存和修改文件的彩色指示器
每个脚本检查当前目录是否是 git 存储库,计算暂存和修改文件,并显示颜色编码的指示器:

成本和持续时间跟踪

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

显示多行

你的脚本可以输出多行来创建更丰富的显示。
一个多行状态行,显示第一行上的模型名称、目录、git 分支,第二行上的上下文使用进度条、成本和持续时间
此示例结合了几种技术:基于阈值的颜色(70% 以下为绿色,70-89% 为黄色,90%+ 为红色)、进度条和 git 分支信息。每个 print 或 echo 语句创建单独的行:
此示例创建指向你的 GitHub 存储库的可点击链接。按住 Cmd(macOS)或 Ctrl(Windows/Linux)并单击以在浏览器中打开链接。
一个状态行,显示指向 GitHub 存储库的可点击链接
每个脚本获取 git 远程 URL,将 SSH 格式转换为 HTTPS,并将存储库名称包装在 OSC 8 转义码中。Bash 版本使用 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 路由命令,这都有效:
或者,当安装了 Git Bash 时,直接运行 Bash 脚本:

提示

  • 使用模拟输入测试: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 这样的命令可能会导致延迟。请参阅缓存示例了解如何处理这个问题。
社区项目如 ccstatusline 和 starship-claude 提供带有主题和其他功能的预构建配置。

故障排除

如果状态栏为空白,请先查看状态栏未出现。尚未信任的文件夹以及运行失败的脚本也会导致状态栏为空白,具体请参见需要工作区信任和脚本错误或挂起。

状态栏未出现

如果您已配置状态栏,但界面底部没有任何显示,请逐项进行以下检查:
  • 验证您的脚本是可执行的: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 背后的计算公式,请参见上下文窗口字段。 链接是否可点击取决于您的终端、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 响应所报告的上下文大小,而不是旋转指示器旁边的每轮计数
  • 在窄终端上,这些通知可能会截断您的状态栏输出