- 你想在工作时监控上下文窗口使用情况
- 你需要跟踪会话成本
- 你在多个会话中工作,需要区分它们
- 你希望 git 分支和状态始终可见

设置状态行
使用/statusline 命令让 Claude Code 为你生成脚本,或手动创建脚本并将其添加到你的设置中。
使用 /statusline 命令
/statusline 命令接受描述你想显示的内容的自然语言指令。Claude Code 在 ~/.claude/ 中生成脚本文件并自动更新你的设置:
手动配置状态行
将statusLine 字段添加到你的用户设置(~/.claude/settings.json,其中 ~ 是你的主目录)或项目设置。将 type 设置为 "command" 并将 command 指向脚本路径或内联 shell 命令。有关创建脚本的完整演练,请参阅逐步构建状态行。
command 字段在 shell 中运行,所以你也可以使用内联命令而不是脚本文件。此示例使用 jq 解析 JSON 输入并显示模型名称和上下文百分比:
padding 字段为状态行内容添加额外的水平间距(以字符为单位)。默认为 0。此填充是在界面的内置间距之外的,所以它控制相对缩进而不是距离终端边缘的绝对距离。
禁用状态行
运行/statusline 并要求它删除或清除你的状态行(例如,/statusline delete、/statusline clear、/statusline remove it)。你也可以手动从 settings.json 中删除 statusLine 字段。
逐步构建状态行
本演练展示了通过手动创建显示当前模型、工作目录和上下文窗口使用百分比的状态行来了解幕后发生的情况。使用
/statusline和你想要的内容的描述会自动为你配置所有这些。
创建一个读取 JSON 并打印输出的脚本
Claude Code 通过 stdin 向你的脚本发送 JSON 数据。此脚本使用
jq,一个你可能需要安装的命令行 JSON 解析器,来提取模型名称、目录和上下文百分比,然后打印格式化的行。将其保存到 ~/.claude/statusline.sh(其中 ~ 是你的主目录,例如 macOS 上的 /Users/username 或 Linux 上的 /home/username):状态行如何工作
Claude Code 运行你的脚本并通过 stdin 向其传输JSON 会话数据。你的脚本读取 JSON,提取它需要的内容,并将文本打印到 stdout。Claude Code 显示你的脚本打印的任何内容。 何时更新 你的脚本在每条新的助手消息之后、权限模式更改时或 vim 模式切换时运行。更新在 300ms 处进行防抖,这意味着快速更改会批处理在一起,你的脚本在事情稳定后运行一次。如果在你的脚本仍在运行时触发新的更新,则会取消正在进行的执行。如果你编辑你的脚本,更改在 Claude Code 的下一次交互触发更新之前不会出现。 你的脚本可以输出什么- 多行:每个
echo或print语句显示为单独的行。请参阅多行示例。 - 颜色:使用ANSI 转义码,如
\033[32m表示绿色(终端必须支持它们)。请参阅git 状态示例。 - 链接:使用OSC 8 转义序列使文本可点击(macOS 上为 Cmd+click,Windows/Linux 上为 Ctrl+click)。需要支持超链接的终端,如 iTerm2、Kitty 或 WezTerm。请参阅可点击链接示例。
状态行在本地运行,不消耗 API 令牌。在某些 UI 交互期间,它会临时隐藏,包括自动完成建议、帮助菜单和权限提示。
可用数据
Claude Code 通过 stdin 向你的脚本发送以下 JSON 字段:| 字段 | 描述 |
|---|---|
model.id, model.display_name | 当前模型标识符和显示名称 |
cwd, workspace.current_dir | 当前工作目录。两个字段包含相同的值;为了与 workspace.project_dir 保持一致,首选 workspace.current_dir。 |
workspace.project_dir | 启动 Claude Code 的目录,如果在会话期间工作目录更改,可能与 cwd 不同 |
cost.total_cost_usd | 总会话成本(美元) |
cost.total_duration_ms | 自会话开始以来的总挂钟时间(毫秒) |
cost.total_api_duration_ms | 等待 API 响应的总时间(毫秒) |
cost.total_lines_added, cost.total_lines_removed | 更改的代码行数 |
context_window.total_input_tokens, context_window.total_output_tokens | 整个会话中的累积令牌计数 |
context_window.context_window_size | 最大上下文窗口大小(令牌)。默认为 200000,或对于具有扩展上下文的模型为 1000000。 |
context_window.used_percentage | 预计算的已使用上下文窗口百分比 |
context_window.remaining_percentage | 预计算的剩余上下文窗口百分比 |
context_window.current_usage | 来自最后一次 API 调用的令牌计数,在上下文窗口字段中描述 |
exceeds_200k_tokens | 最近一次 API 响应中的总令牌计数(输入、缓存和输出令牌合并)是否超过 200k。这是一个固定阈值,与实际上下文窗口大小无关。 |
session_id | 唯一的会话标识符 |
transcript_path | 对话记录文件的路径 |
version | Claude Code 版本 |
output_style.name | 当前输出样式的名称 |
vim.mode | 启用vim 模式时的当前 vim 模式(NORMAL 或 INSERT) |
agent.name | 使用 --agent 标志或配置的代理设置运行时的代理名称 |
worktree.name | 活跃 worktree 的名称。仅在 --worktree 会话期间出现 |
worktree.path | worktree 目录的绝对路径 |
worktree.branch | worktree 的 Git 分支名称(例如,"worktree-my-feature")。对于基于钩子的 worktree 不存在 |
worktree.original_cwd | Claude 进入 worktree 之前所在的目录 |
worktree.original_branch | 进入 worktree 之前检出的 Git 分支。对于基于钩子的 worktree 不存在 |
完整 JSON 架构
完整 JSON 架构
你的状态行命令通过 stdin 接收此 JSON 结构:可能不存在的字段(不在 JSON 中):
vim:仅在启用 vim 模式时出现agent:仅在使用--agent标志或配置的代理设置运行时出现worktree:仅在--worktree会话期间出现。当存在时,branch和original_branch对于基于钩子的 worktree 也可能不存在
null 的字段:context_window.current_usage:在会话中第一次 API 调用之前为nullcontext_window.used_percentage,context_window.remaining_percentage:在会话早期可能为null
上下文窗口字段
context_window 对象提供了两种跟踪上下文使用情况的方式:
- 累积总计(
total_input_tokens,total_output_tokens):整个会话中所有令牌的总和,用于跟踪总消耗 - 当前使用情况(
current_usage):来自最近一次 API 调用的令牌计数,使用此来获得准确的上下文百分比,因为它反映了实际的上下文状态
current_usage 对象包含:
input_tokens:当前上下文中的输入令牌output_tokens:生成的输出令牌cache_creation_input_tokens:写入缓存的令牌cache_read_input_tokens:从缓存读取的令牌
used_percentage 字段仅从输入令牌计算:input_tokens + cache_creation_input_tokens + cache_read_input_tokens。它不包括 output_tokens。
如果你从 current_usage 手动计算上下文百分比,使用相同的仅输入公式来匹配 used_percentage。
current_usage 对象在会话中第一次 API 调用之前为 null。
示例
这些示例展示了常见的状态行模式。要使用任何示例:- 将脚本保存到文件,如
~/.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 响应的时间。
每个脚本将成本格式化为货币并将毫秒转换为分钟和秒:

显示多行
你的脚本可以输出多行来创建更丰富的显示。每个echo 语句在状态区域中产生单独的行。

print 或 echo 语句创建单独的行:
可点击链接
此示例创建指向你的 GitHub 存储库的可点击链接。它读取 git 远程 URL,使用sed 将 SSH 格式转换为 HTTPS,并将存储库名称包装在 OSC 8 转义码中。按住 Cmd(macOS)或 Ctrl(Windows/Linux)并单击以在浏览器中打开链接。

printf '%b',它比 echo -e 更可靠地跨不同 shell 解释反斜杠转义:
缓存昂贵的操作
你的状态行脚本在活跃会话期间频繁运行。像git status 或 git diff 这样的命令可能很慢,特别是在大型存储库中。此示例将 git 信息缓存到临时文件,并仅每 5 秒刷新一次。
为缓存文件使用稳定的固定文件名,如 /tmp/statusline-git-cache。每个状态行调用作为新进程运行,所以基于进程的标识符如 $$、os.getpid() 或 process.pid 每次都产生不同的值,缓存永远不会被重用。
每个脚本在运行 git 命令之前检查缓存文件是否缺失或早于 5 秒:
Windows 配置
在 Windows 上,Claude Code 通过 Git Bash 运行状态行命令。你可以从该 shell 调用 PowerShell:提示
- 使用模拟输入测试:
echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25}}' | ./statusline.sh - 保持输出简短:状态栏的宽度有限,所以长输出可能会被截断或换行不当
- 缓存慢速操作:你的脚本在活跃会话期间频繁运行,所以像
git status这样的命令可能会导致延迟。请参阅缓存示例了解如何处理这个问题。
故障排除
状态行未出现- 验证你的脚本是可执行的:
chmod +x ~/.claude/statusline.sh - 检查你的脚本输出到 stdout,而不是 stderr
- 手动运行你的脚本以验证它产生输出
- 如果
disableAllHooks在你的设置中设置为true,状态行也会被禁用。删除此设置或将其设置为false以重新启用。 - 运行
claude --debug以记录会话中第一次状态行调用的退出代码和 stderr - 要求 Claude 读取你的设置文件并直接执行
statusLine命令以显示错误
-- 或空值
- 在第一次 API 响应完成之前,字段可能为
null - 在你的脚本中使用回退处理 null 值,如 jq 中的
// 0 - 如果值在多条消息后仍然为空,请重新启动 Claude Code
- 使用
used_percentage获得准确的上下文状态,而不是累积总计 total_input_tokens和total_output_tokens在整个会话中是累积的,可能超过上下文窗口大小- 上下文百分比可能与
/context输出不同,因为每个的计算时间不同
- 验证你的终端支持 OSC 8 超链接(iTerm2、Kitty、WezTerm)
- Terminal.app 不支持可点击链接
- SSH 和 tmux 会话可能根据配置剥离 OSC 序列
- 如果转义序列显示为文字文本,如
\e]8;;,使用printf '%b'而不是echo -e以获得更可靠的转义处理
- 复杂的转义序列(ANSI 颜色、OSC 8 链接)如果与其他 UI 更新重叠,偶尔会导致输出混乱
- 如果你看到损坏的文本,尝试简化你的脚本为纯文本输出
- 带有转义码的多行状态行比单行纯文本更容易出现渲染问题
- 以非零代码退出或不产生输出的脚本会导致状态行变为空白
- 慢速脚本会阻止状态行更新,直到它们完成。保持脚本快速以避免陈旧输出。
- 如果在慢速脚本运行时触发新的更新,正在进行的脚本会被取消
- 在配置之前使用模拟输入独立测试你的脚本
- 系统通知,如 MCP 服务器错误、自动更新和令牌警告,显示在与你的状态行相同行的右侧
- 启用详细模式会向此区域添加令牌计数器
- 在窄终端上,这些通知可能会截断你的状态行输出