statusline-generator

状态栏生成器

为 Claude Code 提供单一可信来源的状态栏。一个脚本，两种布局，端到端自验证。

快速健康检查（出问题时从这里开始）

每当状态栏出现异常时，先运行此检查。它能捕获导致大多数“配置了但无法正常工作”报告的隐蔽故障：

bash scripts/health_check.sh

它会验证以下四个层面：

1. ~/.claude/statusline.sh 存在且可执行。忘记运行 chmod +x 是最常见的隐蔽故障原因——Claude Code 会运行脚本，但 exec 失败，状态栏变为空白。
2. ~/.claude/settings.json 包含有效的 statusLine 配置块，并指向该脚本。
3. 使用模拟 stdin 测试完整数据、零令牌、缺失字段、$HOME 路径缩短，以及零分叉 git 分支渲染（通过合成的 .git/HEAD 实现——无需 git 二进制文件）。
4. 如果之前运行时设置了 CLAUDE_STATUSLINE_DEBUG=1，则使用 /tmp/.claude-statusline-last-stdin.json 进行真实 stdin 回放。

每项故障都会打印一条修复命令——无需阅读文档即可恢复。

快速安装

bash scripts/install_statusline.sh

此脚本会：

• 备份任何现有的 ~/.claude/statusline.sh 和 settings.json。
• 将 generate_statusline.sh 复制到 ~/.claude/statusline.sh，并运行 chmod +x。
• 通过 jq 更新 settings.json 中的 statusLine 配置块（保留其他设置）。
• 强制运行 health_check.sh 并显示结果——只有验证通过后，安装才算“完成”。

重启 Claude Code（或发送任意新消息）即可查看状态栏更新。

效果

默认布局——精简的单行布局

~/code/myproject  [main]  Opus 4.7 (1M context)  ctx: 108K / 1M

仅显示必要信息：短路径、git 分支、模型名称、绝对令牌数。不显示颜色、费用或百分比。分支信息通过零分叉方式读取——脚本将 .git/HEAD 作为普通文件读取（处理 worktree/子模块的 gitdir: 间接引用，并支持分离 HEAD 的短 sha），而不是启动 git，因此不会产生额外开销，在没有 git 二进制文件的主机上也能正常工作。

完整布局——包含费用和 git 的多行布局

在 shell 配置文件中设置 CLAUDE_STATUSLINE_LAYOUT=full 即可启用：

alex (Sonnet 4.6) [$0.42/$25.93]  ctx: 108K/1M (11%)
~/code/myproject
[git:main*+]

• 第 1 行：用户、模型、ccusage 会话/每日费用、按颜色编码的 ctx（绿色 ≤50%，黄色 51–80%，红色 >80%）。
• 第 2 行：短路径。
• 第 3 行：git 分支，已修改文件标记为 *，未跟踪文件标记为 +。

布局：如何切换

脚本从环境变量读取布局，而非命令行标志（Claude Code 会通过 stdin 传递 JSON，因此使用标志会产生冲突）。在 ~/.zshrc 或 ~/.bashrc 中设置：

# Minimal (default — same as not setting it)
export CLAUDE_STATUSLINE_LAYOUT=minimal

# Full
export CLAUDE_STATUSLINE_LAYOUT=full

重启 shell（或 source rc 文件），让 Claude Code 继承此更改，然后发送一条消息——状态栏会在 300ms 内刷新。

调试 stdin 捕获

如需查看 Claude Code 实际发送给脚本的 JSON：

export CLAUDE_STATUSLINE_DEBUG=1

每次调用都会将 stdin 写入 /tmp/.claude-statusline-last-stdin.json（每次刷新都会覆盖）。使用 jq . 查看。适用于：

• 诊断字段未按预期渲染的原因。
• 使用真实输入重新运行脚本：cat /tmp/.claude-statusline-last-stdin.json | ~/.claude/statusline.sh。
• 提交错误报告——将转储内容作为确切依据粘贴。

编写规则（为何此技能采用这种设计）

当前设计由三种生产环境故障模式推动。所有防护都已写入代码，而不只是文档：

规则 1——始终运行 chmod +x，并始终通过运行来验证

所有状态栏隐蔽故障中，最主要的原因是脚本缺少可执行权限：Claude Code 的 exec 会静默失败，状态栏变为空白，且没有任何错误提示。install_statusline.sh 始终会运行 chmod +x；如果缺少可执行权限，health_check.sh 会发出提示。如果你手动编写或修改状态栏脚本，请先用模拟测试验证，再宣布完成： echo '{}' | bash your-script.sh。

规则 2——没有证据，“配置完成”毫无意义

“写入了文件并更新了 settings.json”不等于“脚本能够运行并生成预期输出”。因此，install_statusline.sh 会在最后始终运行 health_check.sh，并在任何检查失败时以非零状态码退出。对任何缺乏证据的 Agent 所报告的“完成！”都应保持怀疑。

规则 3——状态栏属于高频路径：要控制子进程开销，而不只是确保正确

状态栏脚本看起来只是 UI 润色，但它会在每个并发 Agent 会话的每次刷新时执行。它启动的任何进程都会随着刷新频率 × 活跃会话数而成倍增加，全天如此。在运行许多并发会话的机器上测得：基于包运行器的状态栏（bunx <pkg>@latest 这种形式，每次刷新都会重新解析注册表并重写锁文件，然后运行 git status + git branch）每次刷新约消耗 0.4 秒 CPU；而此脚本仅消耗约 0.01 秒。在许多会话中，这种差异会明显增加整机的进程活动、发热和电池消耗；在一次真实的电池耗电调查（2026-07）中，状态栏是耗电的主要因素之一。

具体来说：

• 刷新时绝不解析软件包。 statusLine.command 中不要使用 bunx/npx 的 @latest——应固定版本并一次性安装，或使用本地脚本。
• 不要启动 git 来获取分支。 将 .git/HEAD 作为文件读取（参见脚本中的 git_branch_fast）——结果相同，且无需启动子进程。
• 将 git status（脏状态）视为非必需功能。 它会在每次刷新时遍历工作树；只有完整布局会运行它，而且必须显式启用。
• 预算：状态栏每次刷新应只耗费个位数毫秒，最多启动少量进程（此处为一个 jq + 一个 awk）。

关于字段层面的陷阱（会话启动时 used_percentage 为 null、不同 Claude Code 版本中 total_input_tokens 的语义、硬编码的 context_window_size），请参阅 references/context-window-schema.md。

自定义

关于颜色、自定义片段（主机名、时间等）以及关闭费用跟踪，请参阅 references/customization.md。

依赖项

脚本会自动检测可用工具，并在工具不可用时优雅降级：

工具	用途	后备方案
jq	JSON 解析（首选）	改用 python3
python3	JSON 解析后备方案	仅显示原始 cwd
awk	Token 数量的 K/M 格式化	两种布局都需要
git	脏状态 */+ 标记（仅完整布局——最简布局会直接从 .git/HEAD 读取分支，无需 git）	缺失或不在仓库中时静默跳过
ccusage	费用（完整布局）	缺失时静默跳过

macOS 安装命令：brew install jq。Debian/Ubuntu 安装命令：apt install jq。

故障排查

按症状逐项排查，请参阅 references/troubleshooting-decision-tree.md。 其中涵盖：

1. 状态栏空白或从不更新（chmod 原因）
2. ctx 片段缺失或错误（字段陷阱）
3. 想显示 Token 数量而非百分比（切换布局）
4. 颜色显示为原始转义码（终端兼容性）
5. Git 片段缺失（完整布局）
6. 费用片段缺失（ccusage / 缓存）
7. 修改没有效果（路径不匹配）
8. 刷新缓慢（jq 与 python3）

资源

文件	用途
scripts/generate_statusline.sh	状态栏脚本。唯一可信来源。通过 CLAUDE_STATUSLINE_LAYOUT 提供两种布局。
scripts/install_statusline.sh	幂等安装程序。备份、复制、设置执行权限、配置 settings.json 并运行健康检查。
scripts/health_check.sh	四层验证：文件权限、settings.json 配置、模拟 stdin 测试、真实 stdin 重放。
references/troubleshooting-decision-tree.md	根据症状进行诊断的流程图。状态栏运行异常时加载。
references/customization.md	颜色修改、自定义区块、阈值调整、单行完整布局。用户想修改状态栏外观时加载。
references/context-window-schema.md	Claude Code 状态栏 JSON 架构。记录所有字段，以及不同版本中 current_usage 与 total_input_tokens 的语义。
references/color_codes.md	ANSI 颜色代码参考。进行颜色自定义时加载。
references/ccusage_integration.md	ccusage 集成深入说明：缓存、JSON 格式、故障排查。处理费用相关问题时加载。