statusline-generator
- Repo stars 1,187
- Forks 185
- Author updated Jun 14, 2026, 10:01 AM
- Author repo claude-code-skills
- Domain
- Other
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @daymade · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: statusline-generator
description: > A single-source-of-truth statusline for Claude Code. One script, two layouts, end-to-end self-…
category: other
runtime: no special runtime
---
# statusline-generator output preview
## PART A: Task fit
- Use case: > A single-source-of-truth statusline for Claude Code. One script, two layouts, end-to-end self-verification. Run this first whenever the statusline misbehaves. It catches the silent failures runs entirely locally. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Quick health check (start here when something is wrong) / Quick install / What you get” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “> A single-source-of-truth statusline for Claude Code. One script, two layouts, end-to-end self-verification. Run this first whenever the statusline misbehaves. It catches the silent failures runs entirely locally. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “Quick health check (start here when something is wrong) / Quick install / What you get” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/tmp`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Quick health check (start here when something is wrong) / Quick install / What you get”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: statusline-generator
description: > A single-source-of-truth statusline for Claude Code. One script, two layouts, end-to-end self-…
category: other
source: daymade/claude-code-skills
---
# statusline-generator
## When to use
- > A single-source-of-truth statusline for Claude Code. One script, two layouts, end-to-end self-verification. Run this…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Quick health check (start here when something is wrong) / Quick install / What you get” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "statusline-generator" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Quick health check (start here when something is wrong) / Quick install / What you get
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} Statusline Generator
A single-source-of-truth statusline for Claude Code. One script, two layouts, end-to-end self-verification.
Quick health check (start here when something is wrong)
Run this first whenever the statusline misbehaves. It catches the silent failures that account for most "configured but not working" reports:
bash scripts/health_check.sh
It validates four layers:
~/.claude/statusline.shexists and is executable. Missingchmod +xis the single most common silent-failure cause — Claude Code runs the script,execfails, statusline goes blank.~/.claude/settings.jsonhas a validstatusLineblock pointing at the script.- Mock stdin tests covering complete data, zero tokens, missing fields,
and
$HOMEpath shortening. - Real stdin replay from
/tmp/.claude-statusline-last-stdin.jsonif you previously ran withCLAUDE_STATUSLINE_DEBUG=1.
Each failure prints a one-line fix command — you don't have to read documentation to recover.
Quick install
bash scripts/install_statusline.sh
This script:
- Backs up any existing
~/.claude/statusline.shandsettings.json. - Copies
generate_statusline.shto~/.claude/statusline.shandchmod +xs it. - Updates
settings.jsonstatusLineblock viajq(preserves other settings). - Mandatorily runs
health_check.shand shows the result — installation is not "complete" until verification passes.
Restart Claude Code (or send any new message) to see the statusline update.
What you get
Default — minimal one-line layout
~/code/myproject Opus 4.7 (1M context) ctx: 108K / 1M
Just the essentials: short path, model name, absolute token counts. No colors, no git, no cost, no percentage. Designed for users who want signal without noise.
Full — multi-line with cost and git
Set CLAUDE_STATUSLINE_LAYOUT=full in your shell profile to enable:
alex (Sonnet 4.6) [$0.42/$25.93] ctx: 108K/1M (11%)
~/code/myproject
[git:main*+]
- Line 1: user, model, ccusage session/daily costs, color-coded ctx (green ≤50%, yellow 51–80%, red >80%).
- Line 2: short path.
- Line 3: git branch with
*for modified,+for untracked.
Layouts: how to switch
The script reads layout from environment, not flags (Claude Code passes JSON on stdin,
so flags would conflict). Set in ~/.zshrc or ~/.bashrc:
# Minimal (default — same as not setting it)
export CLAUDE_STATUSLINE_LAYOUT=minimal
# Full
export CLAUDE_STATUSLINE_LAYOUT=full
Restart your shell (or source the rc file) so Claude Code inherits the change,
then send a message — statusline refreshes within 300ms.
Debug stdin capture
To see exactly what JSON Claude Code sends your script:
export CLAUDE_STATUSLINE_DEBUG=1
Each invocation writes its stdin to /tmp/.claude-statusline-last-stdin.json
(overwriting on every refresh). Inspect with jq .. Useful for:
- Diagnosing why a field doesn't render the way you expect.
- Re-running the script against real input:
cat /tmp/.claude-statusline-last-stdin.json | ~/.claude/statusline.sh. - Filing bug reports — paste the dump as ground truth.
Authoring rules (why this skill is shaped this way)
Two production failure modes drove the current design. Both are sealed in code, not just docs:
Rule 1 — Always chmod +x, always verify by running
The single biggest silent-failure cause of any statusline is a script without
the executable bit: Claude Code's exec fails silently and the bar goes blank
with no error. install_statusline.sh always chmod +xs; health_check.sh
flags the bit if missing. If you hand-write or hand-edit a statusline script,
mock-test it before declaring done: echo '{}' | bash your-script.sh.
Rule 2 — "Configuration complete" is meaningless without evidence
"Wrote the file and updated settings.json" is not the same as "the script runs
and produces the expected output." install_statusline.sh therefore always
runs health_check.sh at the end and exits non-zero if any check fails.
Treat any "complete!" report from any agent that lacks evidence as suspect.
For field-level traps (used_percentage null at session start, total_input_tokens
semantics across Claude Code versions, hardcoded context_window_size), see
references/context-window-schema.md.
Customization
For colors, custom segments (hostname, time, etc.), and disabling cost tracking,
see references/customization.md.
Dependencies
The script auto-detects available tools and degrades gracefully:
| Tool | Required for | Fallback |
|---|---|---|
jq |
JSON parsing (preferred) | falls back to python3 |
python3 |
JSON parsing fallback | bare cwd only |
awk |
token K/M formatting | required by both layouts |
git |
git status (full layout) | silent skip if missing or not in repo |
ccusage |
cost (full layout) | silent skip if missing |
Install on macOS: brew install jq. On Debian/Ubuntu: apt install jq.
Troubleshooting
For symptom-by-symptom diagnostics, see
references/troubleshooting-decision-tree.md.
It walks through:
- Statusline blank or never updates (chmod cause)
- ctx segment missing or wrong (field traps)
- Want token counts not percentages (layout switch)
- Colors render as raw escape codes (terminal compatibility)
- Git segment missing (full layout)
- Cost segment missing (ccusage / cache)
- Edits have no effect (path mismatch)
- Slow refresh (jq vs python3)
Resources
| File | Purpose |
|---|---|
scripts/generate_statusline.sh |
The statusline script. Single source of truth. Two layouts via CLAUDE_STATUSLINE_LAYOUT. |
scripts/install_statusline.sh |
Idempotent installer. Backs up, copies, chmods, wires settings.json, runs health check. |
scripts/health_check.sh |
Four-layer verification: file perms, settings.json wiring, mock stdin tests, real stdin replay. |
references/troubleshooting-decision-tree.md |
Symptom-driven diagnostic flowchart. Load when statusline misbehaves. |
references/customization.md |
Color changes, custom segments, threshold tuning, single-line full layout. Load when user wants to modify how the statusline looks. |
references/context-window-schema.md |
Claude Code statusline JSON schema. Documents every field plus current_usage vs total_input_tokens semantics across versions. |
references/color_codes.md |
ANSI color codes reference. Load for color customization. |
references/ccusage_integration.md |
ccusage integration deep-dive: caching, JSON shape, troubleshooting. Load for cost-related issues. |
Decide Fit First
Design Intent
How To Use It
Boundaries And Review