Claude Code Statusline 配置:可用脚本、字段与排障
个人初版可用 /statusline 生成;想控制字段和缺值处理,就用手动脚本。先用模拟 JSON 跑出一行输出,再配置作用域,定位空白、旧值及 Windows 路径问题。
文章目录

配置 Claude Code statusline,直接的起点是在会话里输入 /statusline,告诉它你想看哪些信息。想自己维护代码,则在设置中添加 statusLine 命令:Claude Code 把会话 JSON 送到标准输入(stdin),脚本把状态栏文字写到标准输出(stdout)。先让模型、项目、分支和上下文用量稳定显示,再考虑主题、颜色或更多指标。官方状态栏文档说明了这两种设置方式。
选哪条路,取决于你想控制什么:
| 需求 | 建议起点 | 完成时应看到什么 |
|---|---|---|
| 给自己快速做一个状态栏 | /statusline 生成 | 生成脚本和配置,底部出现所需信息 |
| 自己决定字段、缺值和输出格式 | 手动配置下文的小脚本 | 模拟输入能输出预期文字,再接入会话 |
| 团队使用同一份行为 | 共享项目设置和仓库内脚本 | 同事能运行相同路径,不依赖你的个人目录 |
| 需要主题、多行布局和可视化编辑 | 选用第三方 formatter | 能配置所需布局,并接受相应依赖和数据访问 |
共享项目设置是配置的作用域,也可以使用手动脚本;它不是另一套状态栏协议。下面先给出个人设置的完整流程,再说明如何共享和排障。
用 /statusline 生成个人初版
在 Claude Code 会话中输入:
/statusline 显示当前模型、当前项目目录、Git 分支和上下文已用百分比。保持一行,缺少数据时显示“—”,不要把缺值当成 0。Claude Code 会生成脚本并更新设置。生成后,查看它保存的脚本与命令路径,确认输出的是你需要的信息;成功信号是底部出现相应状态栏,而不只是收到“配置完成”的文字回复。官方说明允许用自然语言继续调整或清除状态栏。
当你想明确控制每个字段、让同事能复现,或者定位生成脚本的问题时,使用下面的手动方式。这里的命令和路径是给你在自己的环境中操作的示例。
手动配置:先把一份完整脚本跑通
这个例子显示模型、项目名、分支、上下文已用百分比和会话费用估算;收到有效的五小时或七天用量窗口时再追加相应段落。它只读取输入 JSON,并按需对输入目录执行只读 Git 查询,不访问网络、不读取凭据或会话记录。
前提是本机有可用的 Node.js。先在终端执行 node --version 确认解释器能启动;安装了 Claude Code 不代表机器上一定有独立的 node 命令。Git 是可选依赖:没有 Git、目录不可访问或查询失败时,分支显示“—”,其他段落照常输出。

1. 保存脚本
macOS、Linux 可先创建个人脚本目录:
mkdir -p "$HOME/bin"把以下完整代码保存为 ~/bin/claude-statusline.cjs。Windows 也使用同一份 .cjs 文件,命令路径在后面的 Windows 小节调整。
const { readFileSync } = require("node:fs");
const { spawnSync } = require("node:child_process");
const object = (v) =>
v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
const number = (v) => typeof v === "number" && Number.isFinite(v);
const text = (v) => typeof v === "string"
? v.replace(/[\x00-\x1f\x7f|]/g, " ").trim()
: "";
let data = {};
try {
data = object(JSON.parse(readFileSync(0, "utf8")));
} catch {
console.error("statusline: 输入不是可解析的 JSON");
process.stdout.write("状态数据不可读\n");
process.exit(0);
}
const model = object(data.model);
const workspace = object(data.workspace);
const context = object(data.context_window);
const cost = object(data.cost);
const worktree = object(data.worktree);
const pathValue = (v) => typeof v === "string" && v.length ? v : "";
const directory = pathValue(workspace.current_dir) || pathValue(data.cwd);
const project = text(directory.split(/[\\/]/).filter(Boolean).pop()) || "—";
function git(args) {
if (!directory) return "";
const result = spawnSync("git", ["-C", directory, ...args], {
encoding: "utf8", timeout: 500, maxBuffer: 4096,
windowsHide: true
});
return !result.error && result.status === 0 ? text(result.stdout) : "";
}
let branch = text(worktree.branch);
if (!branch) {
branch = git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
if (!branch) {
const commit = git(["rev-parse", "--short", "HEAD"]);
branch = commit ? `游离:${commit}` : "—";
}
}
const parts = [
text(model.display_name) || text(model.id) || "模型:—",
`项目:${project}`,
`分支:${branch}`,
number(context.used_percentage)
? `上下文:${context.used_percentage.toFixed(1)}%` : "上下文:—",
number(cost.total_cost_usd) && cost.total_cost_usd >= 0
? `估算:USD ${cost.total_cost_usd.toFixed(2)}` : "估算:—"
];
const windows = object(data.rate_limits);
const now = Date.now() / 1000;
for (const [key, label] of [["five_hour", "五小时"], ["seven_day", "七天"]]) {
const window = object(windows[key]);
if (number(window.used_percentage) &&
number(window.resets_at) && window.resets_at > now) {
parts.push(`${label}已用:${window.used_percentage.toFixed(1)}%`);
}
}
process.stdout.write(parts.join(" | ") + "\n");.cjs 让这份代码使用 Node 的 CommonJS 模块,不受项目 package.json 的模块类型影响。我们显式用 node 读取脚本,因此不需要给脚本加 chmod +x;直接把脚本路径当作可执行命令则有不同的解释器和权限要求。
普通 Git 分支不是当前 JSON 中的通用 git.branch 字段。这份脚本先采用可用的 worktree.branch,否则通过 git -C 查询 输入提供的目录,避免误显示终端当前目录的分支。游离 HEAD 显示短提交号;新仓库尚未提交但已有分支名时,仍能显示该分支。它不查询未提交文件,也不把分支名当成“工作区干净”的证明。Git 子进程设置了超时,查询失败会退回“—”;这不是整条状态栏的耗时保证。
2. 用模拟 JSON 确认输出
在当前目录新建 statusline-demo.json,内容如下。这里的项目路径、用量和费用都是虚构数据;resets_at 设为 2100 年的时间戳,便于离线演示未过期窗口。
{
"model": {"id": "demo-model", "display_name": "Claude 演示模型"},
"workspace": {"current_dir": "/demo/demo-app"},
"worktree": {"branch": "feature/demo"},
"context_window": {"used_percentage": 42},
"cost": {"total_cost_usd": 0.18},
"rate_limits": {
"five_hour": {"used_percentage": 0, "resets_at": 4102444800}
}
}macOS、Linux 在该文件所在目录执行:
node "$HOME/bin/claude-statusline.cjs" < statusline-demo.json预期输出是一行纯文本:
Claude 演示模型 | 项目:demo-app | 分支:feature/demo | 上下文:42.0% | 估算:USD 0.18 | 五小时已用:0.0%注意最后的 0.0%:这是输入明确给出的数值 0。把 used_percentage 改成 null,上下文会显示“—”;删掉 five_hour 或把它的 resets_at 改为已经过去的时间,五小时段落会消失。它们都不意味着“已用 0%”或“没有限额”。
本例代码已用合成 JSON、缺值与类型变化、过期时间以及隔离的 Git 仓库做离线检查。这里的预期输出只验证脚本处理,不代表真实 Claude Code 界面、Windows 客户端或账户用量已经实测。
3. 添加 statusLine 设置
个人跨项目使用时,把下面的键合入用户设置文件 ~/.claude/settings.json。保留已有键,不要把整份设置覆盖成这个片段。
{
"statusLine": {
"type": "command",
"command": "node \"$HOME/bin/claude-statusline.cjs\""
}
}type 和 command 描述如何启动脚本,主状态栏的 stdout 是显示文字,不要求返回 { "text": "..." } 一类 JSON 对象。错误说明放在 stderr,避免污染显示。当前配置项说明还提供 padding、refreshInterval 和 hideVimModeIndicator 等可选项;第一版不必全加。
修改命令会立即触发运行;只编辑脚本文件时,要等下一个刷新事件。接入后的成功信号是模型和项目等段落出现在底部,并在后续会话变化时更新。第一次响应之前,上下文或用量可能尚无数据,显示“—”不等于安装失败。
字段怎么选,哪些值不能互相替代
日常先保留能帮你判断“在哪个项目、用哪个模型、上下文还够不够”的信息。费用、套餐窗口和缓存各有口径,不能把它们混成同一个使用率。官方完整 JSON 说明列出了当前字段和出现条件。
| 想显示的信息 | 当前字段或获取方式 | 读数含义与缺值处理 |
|---|---|---|
| 模型名称 | model.display_name,回退到 model.id | model 是对象,不能当作平面字符串 |
| 当前目录 | workspace.current_dir 或 cwd | workspace.project_dir 是启动目录,可能与当前目录不同 |
| 普通分支 | 对输入目录执行只读 Git 查询 | 没有通用 git.branch;特定 worktree 会话可有 worktree.branch |
| 上下文已用比例 | context_window.used_percentage | 最新响应对应的当前上下文;可能为 null,数值 0 应保留 |
| 会话费用估算 | cost.total_cost_usd | 客户端按模型价格估算的会话成本,不是实际账单 |
| 五小时、七天用量 | rate_limits.five_hour、seven_day | 其中 used_percentage 表示已用,resets_at 单位是 Unix 秒 |
上下文用量不是累计消耗,也不是套餐余额
context_window.current_usage 在第一次 API 响应前、以及 /compact 后尚未收到下一次响应时,可能为 null,百分比也可能暂时缺失。当前输入 token 总量包含 input_tokens、cache_creation_input_tokens 和 cache_read_input_tokens;used_percentage 依据这些输入计算,不把输出 token 加进去。
因此,不能把当前上下文 token 除以一个自设的套餐额度,算出“订阅还剩多少”。/context 还会估算新加入但尚未发送的内容,它显示的用量可能高于状态栏的最近一次响应值;两处数字有差异不一定是脚本错误。上下文与更新口径见官方说明。
费用估算不能确认扣款或付费账户
cost.total_cost_usd 可以帮你观察会话成本变化,但它是客户端估算,既不证明谁承担账单,也不代表订阅实际扣了相同金额。累计运行时间 total_duration_ms 与 API 等待时间 total_api_duration_ms 的单位都是毫秒;显示秒数时要除以 1,000。当前文档还说明,从 v2.1.211 起,/clear 开始的新会话会从 0 重新计算成本,旧版本行为不同。成本字段说明给出了适用口径。
套餐窗口和网关支出有独立条件
当前 rate_limits 只在 claude.ai Pro/Max 订阅或设有支出上限的 Claude apps gateway 路线下、首次 API 响应后出现。五小时、七天和 spend_limit 窗口可以分别缺失,过了各自 resets_at 后会被移除。某个段落消失时,不能推断额度为零、额度无限或 API key 出错。用量字段条件以官方文档为准。
网关的 spend_limit.used_percentage 可超过 100%,要求 v2.1.251;可选的 used_usd、limit_usd 和 period 要求客户端及网关均达到 v2.1.284。美元金额大约每五分钟独立更新,可能落后于百分比,关闭非必要流量时也可能不提供这些可选值。不要通过改组织流量策略来“补齐”状态栏。
缓存指标也应单独看:prompt_cache 从 v2.1.251 起提供主对话统计,首次响应后才出现,hit_ratio 是 0–1 或 null,不包含子代理调用。缓存未命中可能来自压缩或工具结果重建等多种情况,单个低值不能证明提示词写错。如果第一行已经够用,可以不显示它。
设置作用域决定谁会使用这条命令
个人偏好通常放用户设置;仅当前项目自己使用的覆盖放项目本地设置;要团队共同维护时,才把脚本和共享设置一起提交。常见位置如下,Git worktree、本地主目录归属及 Windows 情况可能改变实际本地设置位置,先看客户端加载了哪些文件。官方设置文档说明了作用域和路径规则。
| 作用域 | 常见文件或入口 | 适用场景 |
|---|---|---|
| 用户 | ~/.claude/settings.json | 个人跨项目默认值 |
| 项目本地 | .claude/settings.local.json | 自己对一个项目的覆盖,不作为团队标准 |
| 共享项目 | .claude/settings.json | 随仓库共享的行为及非私人路径 |
| 命令行 | --settings | 启动时的临时覆盖 |
| 托管 | 组织管理员提供 | 组织控制的配置 |
同一个键的优先级从高到低是:托管、命令行、项目本地、共享项目、用户。未指定的键仍可沿用较低层设置;不能把所有配置理解成整份文件覆盖,列表等类型还有自己的合并规则。
例如,团队把上面的脚本保存为仓库内 tools/claude-statusline.cjs,共享设置可以使用:
{
"statusLine": {
"type": "command",
"command": "node \"./tools/claude-statusline.cjs\""
}
}同事需要有可用的 Node.js,并从对应项目目录启动;目录变化后重新确认相对路径。提交前检查脚本行为和依赖,个人绝对路径、凭据与私人状态不要写进共享文件。/status 的 Setting sources 可以查看已加载的设置文件,但它不会逐键告诉你究竟是哪一份提供了 statusLine。
更新慢、值不变:先分清触发与数据来源
状态栏会在启动或恢复会话、助手消息、/compact 完成、权限模式或 Vim 状态变化等事件后运行。更新有 300 毫秒防抖,命令改变会立即运行;新更新会取消仍在运行的旧脚本。限额、缓存时间戳到期,以及配置的计时器也可以触发刷新。运行生命周期见官方文档。
所以,“编辑脚本后立刻没变化”和“每次输出都卡住”应分开处理:前者等下一次触发,后者先查看脚本是否访问网络、扫描大文件或执行慢命令。stdout 是被捕获的输出,不是直接连接终端的 TTY;自适应宽度可读客户端提供的 COLUMNS,不要依赖 tput cols 一定能读到终端宽度。
如果你确实显示时钟、随时间变化的外部状态,才考虑给已有对象加上:
"refreshInterval": 10这是 10 秒,当前最小值为 1 秒。定时重跑只保证脚本重新执行,不保证上游用量也获得了新测量。慢脚本不会靠更频繁刷新变快;若引入缓存,应按会话和目录区分,避免切项目后仍显示上个仓库的结果。
Windows:先验证解释器和路径
当前官方文档说明,Windows 安装 Git Bash 时会使用它,否则使用 PowerShell;不能把所有 Windows 环境都当成同一种 shell。下面给 Node 脚本指定完整路径,减少相对目录与 ~ 展开的差异:Windows 配置示例。
{
"statusLine": {
"type": "command",
"command": "node \"C:/Users/你的用户名/bin/claude-statusline.cjs\""
}
}把用户名换成自己的实际目录;如果 node 不在客户端能使用的 PATH 中,命令里的解释器也要改成带引号的绝对路径。路径内有空格时保留引号。JSON 中反斜杠需要转义,这里用正斜杠避免混淆。
在 PowerShell 中,可在模拟文件所在目录先测试:
Get-Content -Raw -Encoding UTF8 ./statusline-demo.json | node "C:/Users/你的用户名/bin/claude-statusline.cjs"成功时应看到前面那行模拟输出。若乱码或空白,核对当前 PowerShell/终端的 UTF-8 编码与 Node 路径,再检查 Claude Code 实际使用的命令。以上是依据当前文档编写的 Windows 操作示例,未作 Windows 客户端实测。
需要主题和布局时,再选第三方 formatter
当你要多行组件、Powerline 主题、可视化调整和导入导出布局时,可以考虑 ccstatusline。它的项目 README 给出的快速入口是:
npx -y ccstatusline@latest这是下载并运行第三方包,所需 npm/Node 环境与自行维护一个 .cjs 脚本不同。初始 TUI 提供的 Pinned global install 会把选定版本安装到全局,并写入固定版本的命令;固定安装后,ccstatusline 可打开 TUI。工具自身的配置位于 ~/.config/ccstatusline/settings.json,不要与 Claude 的设置文件混淆。
选择它的理由是已有的主题和布局功能,不是未经验证的“最快”或“最安全”。一些用量组件会查找凭据或 macOS Keychain、直接访问 Anthropic usage API;部分指标读取会话记录或缓存,服务健康组件也使用网络数据。因此,不能把整个工具说成只读官方 stdin JSON、全程离线。按自己要启用的组件判断依赖;这里未安装或运行该工具,也未读取任何凭据或真实使用数据。
如果只需要前面几个字段,保留小脚本就能完成任务。要停用自定义状态栏,移除对应设置中的 statusLine 键,或让 /statusline 清除它;保留其他设置。
空白、缺值、旧数据怎么排查

先在 Claude Code 外,用模拟文件运行 设置中的同一条命令。这一步把脚本、解释器和路径问题与客户端设置问题分开。
| 症状 | 先看什么 | 下一步 |
|---|---|---|
| 终端就无法运行 | 解释器、脚本文件与路径引号 | 修正命令;明确用 node 读取文件时无需加执行位 |
| 有日志但没有状态文字 | stdout 与 stderr 是否写反 | 把显示结果写 stdout,诊断信息写 stderr |
| 显示“状态数据不可读” | 送入脚本的 JSON 是否完整有效 | 先用文中的模拟文件测试,修正解析或传入方式 |
| 有状态栏,但上下文是“—” | 首次响应、压缩后的缺值、字段名 | 等适用的新响应;读 used_percentage,不要读旧 percentage |
| 分支是“—” | 输入目录、Git 是否可用、是否在仓库内 | 在同一目录验证只读查询;不要凭空加 git.branch |
| 五小时或七天段落消失 | 路线条件、首次响应和窗口是否过期 | 视为尚未提供有效窗口,不推断为 0 或无限 |
| 只有旧值,或刷新很慢 | 是否有触发、脚本耗时及缓存归属 | 先简化慢逻辑;外部时间数据才考虑定时刷新 |
| 脚本能跑,会话里完全没有 | 设置来源、拒绝条目和策略限制 | 查看实际加载文件与客户端诊断,再核对下文规则 |
| 纯文本正常,颜色或链接异常 | 终端支持与可用宽度 | 先恢复纯文本,再逐项加 ANSI 或 OSC 8 特性 |
脚本在终端通过后仍不运行,尤其要区分以下两类策略。官方策略条目规定:
- 托管
disableAllHooks=true,或工作区未受信任时,所有自定义statusLine都关闭。 allowManagedHooksOnly、生效的非托管disableAllHooks=true,或--safe-mode会把可运行的配置收窄到托管设置。管理员部署的托管状态栏仍可以运行,个人、项目或插件设置则可能无警告地被跳过。
允许某个托管插件的 hooks,不代表该插件的 statusline 也自动获准;状态栏配置本身必须来自托管设置。遇到组织控制时,把症状和命令测试结果交给管理员核对,不把关闭策略、改信任状态或删除整份设置当作通用修复。
当前客户端会报告部分无效 JSON 或已知无效值,claude doctor 可帮助查看被拒绝的配置条目,不能假设所有错误都静默忽略。此外,帮助或权限提示期间状态栏可能暂时隐藏,通知与窄终端会占用或截断行,不能仅凭一次没看见就判定脚本失效。官方排障说明也列出了这些显示条件。
常见问题
statusline、/statusline 和 statusLine 有什么区别?
statusline 是状态栏功能的常见称呼,/statusline 是会话内的设置命令,statusLine 是 JSON 设置键。写配置时大小写必须准确;它接收 stdin JSON,输出显示文字。
状态栏本身会额外消耗模型 token 吗?
读取已提供的 JSON 并打印文字不会产生一次新的模型请求。本文小脚本也没有网络调用。第三方工具或自定义脚本可能另外访问服务,须按具体代码和组件判断,不能从“statusline”这个名称推出所有实现都离线。
为什么费用显示 0,上下文却不是 0?
它们是不同指标:上下文是当前输入占用,费用是会话成本估算。实际数值 0 应保留,缺少数据则显示“—”;成本估算也不能用来确认扣款或订阅余额。官方字段口径解释了两者的区别。
自定义状态栏只能有一行吗?
不是。官方支持多行、ANSI 颜色和 OSC 8 链接,效果取决于终端能力与空间;例如 macOS Terminal.app 不支持可点击的 OSC 8 链接。本例保持一行是为了便于验证和扫读,不是协议限制。显示能力说明见官方文档。





