Workflow & Core Tools · daymade/claude-code-skills

statusline-generator

Name: statusline-generator
Author: daymade/claude-code-skills

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 数.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit

Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE；GitHub API spdx MIT）Commit d5c4678cb5

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Single Source of Truth architecture: generate_statusline.sh is the sole statusline script (two layouts are toggled via the environment variable CLAUDE_STATUSLINE_LAYOUT rather than flags, because Claude Code passes JSON over stdin and flags would conflict); both installation and health checks center around this single script.

daymade-claude-code/statusline-generator/SKILL.md

The script reads layout from environment, not flags (Claude Code passes JSON on stdin, so flags would conflict).

The header comment of generate_statusline.sh explicitly notes '# Configuration via environment variables (no flags — Claude Code passes JSON on stdin)'; the script first consumes stdin with `input=$(cat)` before parsing.

Zero-fork performance discipline: reads Git branch without spawning git processes by traversing upward to locate and read .git/HEAD as a plain file (handling indirect gitdir: pointers in worktrees/submodules and short SHAs for detached HEADs); refresh budget is millisecond-grade with single-digit forks.

daymade-claude-code/statusline-generator/scripts/generate_statusline.sh

# Zero-fork git branch: walk up to .git and read HEAD as a file. Never spawns # git.

SKILL Rule 3 provides motivational data: 'a package-runner statusline (bunx <pkg>@latest-style…) cost ~0.4s CPU per refresh; this script costs ~0.01s', citing an actual July 2026 battery investigation; the function git_branch_fast handles .git both as a directory and as a gitdir: file.

JSON parsing dependency ladder: prioritizes jq, falls back to python3, and degrades to bare cwd if neither is available; ctx usage is computed by summing input, cache_read, and cache_create; $HOME shortening uses case rather than parameter substitution for cross-shell safety.

daymade-claude-code/statusline-generator/SKILL.md

| `jq` | JSON parsing (preferred) | falls back to `python3` |

generate_statusline.sh implements: 'if command -v jq >/dev/null 2>&1; then parsed=$(parse_with_jq) elif command -v python3 … else echo "$PWD"; exit 0'; awk formats human-readable values like 999/108K/1M/1.5M.

Closed-loop install = copy + chmod + wire-up + self-verification: install_statusline.sh backs up existing ~/.claude/statusline.sh and settings.json, updates only the statusLine block via jq (preserving other settings), enforces chmod +x, and always terminates by executing health_check, exiting with non-zero on failure—an 'installed' state requires concrete proof.

daymade-claude-code/statusline-generator/SKILL.md

**Mandatorily runs `health_check.sh` and shows the result** — installation is not "complete" until verification passes.

The install script comments '# critical — silent failure root cause if missed'; if jq is missing, it refuses to modify settings.json and prints manual editing instructions to prevent corrupting user configuration.

Four-tier validation in health_check.sh: file existence and executability → settings.json wiring → mock stdin coverage (full payload, zero tokens, missing fields, $HOME shortening, synthetic .git/HEAD zero-fork branch) → replay of real stdin captured via CLAUDE_STATUSLINE_DEBUG=1; each failure provides a one-line remediation command.

daymade-claude-code/statusline-generator/SKILL.md

It validates four layers: 1. `~/.claude/statusline.sh` exists and is executable. **Missing `chmod +x` is the single most common silent-failure cause**

Mock tests run the target script directly via bash and grep output patterns (e.g., 'TestModel.*ctx: 100K / 1M') without depending on a running Claude Code instance; debug mode overwrites stdin to /tmp/.claude-statusline-last-stdin.json on each refresh for replay and bug reporting.

Full layout cost section uses ccusage with caching and silent degradation: caches to /tmp/claude_cost_cache_<min>.txt, rebuilds after a >2 minute expiration, and silently skips if ccusage is unavailable; context window percentage thresholds color output as green/yellow/red at 50% and 80%.

daymade-claude-code/statusline-generator/scripts/generate_statusline.sh

# Cost via ccusage (cached, async; silent if ccusage unavailable)

Git dirty state (* / +) is a luxury feature exclusive to the full layout (as git status inspects the working tree on every refresh); the minimal layout defaults to no colors, no cost metrics, and no percentages.

2Core Capabilities

01One-click install with self-verification (backup → wire into settings.json → enforced health check conclusion)

02Dual minimal/full layouts: minimal = short path + branch + model + absolute token count; full = user/cost/percentage/multi-line + git dirty indicators

03Four-tier health check with a one-line remediation command for every failure point (chmod / wiring / schema edge cases / replay)

04stdin JSON debug dump (CLAUDE_STATUSLINE_DEBUG=1 → /tmp/.claude-statusline-last-stdin.json) and real input replay

05Zero-fork branch retrieval (reads .git/HEAD directly, supporting worktrees, submodules, and detached HEAD)

06ccusage cost display (full layout, minute-level caching, silent graceful degradation)

07Symptom-driven troubleshooting (references/troubleshooting-decision-tree.md covering 8 classes: blank, missing ctx, percentage toggle, raw escape codes, missing git segment, missing cost, edits not taking effect, slow refresh)

08Field schema reference (references/context-window-schema.md: used_percentage being null at session start, total_input_tokens cross-version semantics, etc.)

3External Dependencies

Kind	Dependency / Endpoint
cli	jq（JSON 解析首选）
cli	python3（JSON 解析回退）
cli	awk（token K/M 格式化，两布局必需）
cli	git（full 布局脏标记；minimal 读 .git/HEAD 不需 git）
cli	ccusage（full 布局成本，可选）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Local script and command execution: bash generate_statusline.sh (executed by Claude Code on every refresh; internally forks jq/python3/awk/whoami)
本地工作目录: File I/O and artifact generation: install overwrites ~/.claude/statusline.sh via cp and modifies ~/.claude/settings.json via jq (both pre-backed up with .b*)

Audit Notes: Bundles local bash scripts and modifies local configuration files (~/.claude/statusline.sh and settings.json, both secured with timestamped backups and structural jq updates) with no network exfiltration, credential reads, or destructive operations (no user data deleted or altered); ccusage is invoked strictly with --offline for public usage metrics. Caveats: statusline output does not sanitize control characters (ANSI injection via malicious cwd/branch names is a standard terminal consideration), and automatic modification of settings.json is aborted if jq is absent.

5Second-Pass Verification

[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 宿主，未做实机刷新验证；字段语义以文档为准。

6Verdict & Scenarios

Empirically backed hot-path performance discipline: zero-fork branch resolution, strict per-fork budget, explicitly bans package-runner statuslines

Install-and-verify closed loop: an 'installation complete' state is automatically rejected by the script itself unless health check passes

Turns the most common silent failure (missing chmod) into an explicit check with a one-line fix command

Comprehensive, layered documentation: schema references, troubleshooting decision tree, customization guide, and ANSI color codes to eliminate guesswork

Best for: Ideal for Claude Code users setting up or troubleshooting their statusline (including bilingual/Chinese users via localized triggers); for heavy multi-session users sensitive to refresh overhead (minimal mode defaults to zero git subprocesses); and for agents using health_check as the immediate first response when diagnosing statusline issues.

Not for: Not suitable for non-Claude Code hosts (the script consumes Claude Code's proprietary stdin JSON protocol); not needed for users satisfied with percentages who do not require absolute token counts; not meant for users seeking flashy statuslines with heavy icons, dynamic widgets, or multi-line animations—the focus here is minimalism and zero overhead.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload statusline-generator.tar.gz

sha256: 7b68993203365b32…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.