statusline-generator
Installs, configures, customizes, or troubleshoots the Claude Code statusline (cwd, model, token counts). Use when the user wants to set up or change the statusline, switch minimal vs full layouts, show absolute token counts (e.g. ctx 108K / 1M) instead of a percentage, add cost via ccusage or git status, dump the stdin JSON Claude Code passes the script, or fix a statusline that is blank, silent, stuck, shows "permission denied", or stopped updating after a script edit (often a missing chmod +x). Trigger phrases: "configure statusline", "statusline blank", "status line not showing", "statusline broken", "show token count in statusline", 状态栏, 状态栏不显示, 状态栏空白, 显示工作目录, 显示 token 数.
1实现原理 · 为什么它能做到
『单一事实源』架构：generate_statusline.sh 是唯一 statusline 脚本（两套布局由环境变量 CLAUDE_STATUSLINE_LAYOUT 切换，不用 flag，因为 Claude Code 从 stdin 传 JSON、flag 会冲突）；install 与 health check 都围绕同一份脚本展开。
The script reads layout from environment, not flags (Claude Code passes JSON on stdin, so flags would conflict).
零 fork 性能纪律：git 分支不 spawn git，而是向上遍历找 .git/HEAD 当普通文件读（含 worktree/submodule 的 gitdir: 间接与 detached-HEAD 短 sha）；刷新预算毫秒级、个位数 fork。
# Zero-fork git branch: walk up to .git and read HEAD as a file. Never spawns # git.
JSON 解析依赖阶梯：jq 优先、python3 回退、都没有则退化为裸 cwd；ctx 用量由 input/cache_read/cache_create 三段求和，$HOME 缩短用 case 而非参数替换（跨 shell 安全）。
| `jq` | JSON parsing (preferred) | falls back to `python3` |
安装=复制+chmod+接线+自验证闭环：install_statusline.sh 备份既有 ~/.claude/statusline.sh 与 settings.json、jq 只改 statusLine 块（保留其他设置）、强制 chmod +x、末尾必跑 health_check 并以非零退出报告失败——『装完』必须有证据。
**Mandatorily runs `health_check.sh` and shows the result** — installation is not "complete" until verification passes.
health_check.sh 四层验证：文件存在且可执行→settings.json 接线→mock stdin 覆盖（完整数据/零 token/缺字段/$HOME 缩短/合成 .git/HEAD 零 fork 分支）→CLAUDE_STATUSLINE_DEBUG=1 留下的真实 stdin 回放；每失败给一行修复命令。
It validates four layers: 1. `~/.claude/statusline.sh` exists and is executable. **Missing `chmod +x` is the single most common silent-failure cause**
full 布局的成本段走 ccusage 且带缓存/静默降级：缓存文件 /tmp/claude_cost_cache_<min>.txt、>2 分钟过期重建、ccusage 缺失时静默跳过；颜色按 ctx 占比 50/80 分绿黄红。
# Cost via ccusage (cached, async; silent if ccusage unavailable)
2核心能力
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | jq（JSON 解析首选） |
| cli | python3（JSON 解析回退） |
| cli | awk（token K/M 格式化，两布局必需） |
| cli | git（full 布局脏标记；minimal 读 .git/HEAD 不需 git） |
| cli | ccusage（full 布局成本，可选） |
4管控建议与判定依据
- scripts/: 执行本地脚本或命令: bash generate_statusline.sh（Claude Code 每刷新执行；内部 fork jq/python3/awk/whoami
- 本地工作目录: 文件读写与工件输出: install：cp 覆盖 ~/.claude/statusline.sh、jq 改写 ~/.claude/settings.json（两者均先 .b
5第二遍独立确认
- [ok] install 是否真的强制 chmod +x — install_statusline.sh 显式 'chmod +x "$TARGET_PATH" # critical — silent failure root cause if missed'。
- [ok] settings.json 是否保结构更新 — install 用 'jq --arg cmd … .statusLine = {"type":"command","command":$cmd,"padding":(.statusLine.padding // 0)}' 合并；无 jq 分支拒绝编辑并提示手改。
- [ok] health_check 声称的 mock 用例 — run_mock 五例（完整/0 token/缺字段/$HOME 缩短/合成 .git/HEAD 分支）与 SKILL 描述逐条对应。
- [ok] 无网络外发与凭证读取 — 三脚本无 curl/wget/url；ccusage 以 --offline 调用；env 仅 LAYOUT/DEBUG/HOME。
- [ok] ccusage 成本路径缓存语义 — generate 185-210 行：缓存文件 /tmp/claude_cost_cache_$(date +%Y%m%d_%H%M).txt、mmin +2 清理、缺失时后台重建并回退旧缓存。
- [unlocatable] 运行时行为（真实 Claude Code stdin 形状下渲染） — 静态代码+reference 文档（context-window-schema.md）齐备，但本环境无 Claude Code 宿主，未做实机刷新验证；字段语义以文档为准。
6结论
7b68993203365b32…