Statusline Generator

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: 1. ~/.claude/statusline.sh exists and is executable. Missing `chmod +x` is the single most common silent-failure cause — Claude Code runs the script, exec fails, statusline goes blank. 2. ~/.claude/settings.json has a valid statusLine block pointing at the script. 3. Mock stdin tests covering complete data, zero tokens, missing fields, and $HOME path shortening. 4. Real stdin replay from /tmp/.claude-statusline-last-stdin.json if you previously ran with CLAUDE_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.sh and settings.json.
• Copies generate_statusline.sh to ~/.claude/statusline.sh and chmod +xs it.
• Updates settings.json statusLine block via jq (preserves other settings).
• Mandatorily runs `health_check.sh` and 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:

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:

1. Statusline blank or never updates (chmod cause) 2. ctx segment missing or wrong (field traps) 3. Want token counts not percentages (layout switch) 4. Colors render as raw escape codes (terminal compatibility) 5. Git segment missing (full layout) 6. Cost segment missing (ccusage / cache) 7. Edits have no effect (path mismatch) 8. Slow refresh (jq vs python3)

Resources

ccusage Integration Reference

This reference explains how the statusline integrates with ccusage for cost tracking and troubleshooting.

What is ccusage?

ccusage is a command-line tool that tracks Claude Code usage and costs by reading conversation transcripts. It provides session-based and daily cost reporting.

How Statusline Uses ccusage

The statusline script calls ccusage to display session and daily costs:

session=$(ccusage session --json --offline -o desc 2>/dev/null | jq -r '.sessions[0].totalCost' 2>/dev/null | xargs printf "%.2f")
daily=$(ccusage daily --json --offline -o desc 2>/dev/null | jq -r '.daily[0].totalCost' 2>/dev/null | xargs printf "%.2f")

Key Features

1. JSON Output: Uses --json flag for machine-readable output 2. Offline Mode: Uses --offline to avoid fetching pricing data (faster) 3. Descending Order: Uses -o desc to get most recent data first 4. Error Suppression: Redirects errors to /dev/null to prevent statusline clutter

Caching Strategy

To avoid slowing down the statusline, costs are cached:

• Cache File: /tmp/claude_cost_cache_YYYYMMDD_HHMM.txt
• Cache Duration: 2 minutes (refreshes based on minute timestamp)
• Background Refresh: First run fetches costs in background
• Fallback: Uses previous cache (up to 10 minutes old) while refreshing

Cache Behavior

1. First Display: Statusline shows without costs 2. 2-5 Seconds Later: Costs appear after background fetch completes 3. Next 2 Minutes: Cached costs shown instantly 4. After 2 Minutes: New cache generated in background

ccusage JSON Structure

Session Data

{
  "sessions": [
    {
      "sessionId": "conversation-id",
      "totalCost": 0.26206769999999996,
      "inputTokens": 2065,
      "outputTokens": 1313,
      "lastActivity": "2025-10-20"
    }
  ]
}

Daily Data

{
  "daily": [
    {
      "date": "2025-10-20",
      "totalCost": 25.751092800000013,
      "inputTokens": 16796,
      "outputTokens": 142657
    }
  ]
}

Troubleshooting

Costs Not Showing

Symptoms: Statusline appears but no [$X.XX/$X.XX] shown

Possible Causes: 1. ccusage not installed 2. ccusage not in PATH 3. No transcript data available yet 4. Background fetch still in progress

Solutions:

# Check if ccusage is installed
which ccusage

# Test ccusage manually
ccusage session --json --offline -o desc

# Check cache files
ls -lh /tmp/claude_cost_cache_*.txt

# Wait 5-10 seconds and check again (first fetch runs in background)

Slow Statusline

Symptoms: Statusline takes >1 second to appear

Possible Causes: 1. Cache not working (being regenerated too often) 2. ccusage taking too long to execute

Solutions:

# Check cache timestamp
ls -lh /tmp/claude_cost_cache_*.txt

# Test ccusage speed
time ccusage session --json --offline -o desc

# If slow, consider disabling cost tracking by commenting out cost section in script

Incorrect Costs

Symptoms: Costs don't match expected values

Possible Causes: 1. Cache stale (showing old data) 2. ccusage database out of sync 3. Multiple Claude sessions confusing costs

Solutions:

# Clear cache to force refresh
rm /tmp/claude_cost_cache_*.txt

# Verify ccusage data
ccusage session -o desc | head -20
ccusage daily -o desc | head -20

# Check ccusage database location
ls -lh ~/.config/ccusage/

Installing ccusage

If ccusage is not installed:

# Using npm (Node.js required)
npm install -g @anthropic-ai/ccusage

# Or check the official ccusage repository for latest installation instructions

Disabling Cost Tracking

To disable costs (e.g., if ccusage not available), comment out the cost section in generate_statusline.sh:

# Cost information using ccusage with caching
cost_info=""
# cache_file="/tmp/claude_cost_cache_$(date +%Y%m%d_%H%M).txt"
# ... rest of cost section commented out

Then update the final printf to remove %s for cost_info:

printf '\033[01;32m%s\033[00m \033[01;36m(%s)\033[00m\n\033[01;37m%s\033[00m\n%s' \
    "$username" "$model" "$short_path" "$git_info"

ANSI Color Codes Reference

This reference provides ANSI escape codes for customizing statusline colors.

Format

ANSI color codes follow this format:

\033[<attributes>m<text>\033[00m

• \033[ - Escape sequence start
• <attributes> - Color and style codes (see below)
• m - Marks end of escape sequence
• \033[00m - Reset to default

Common Color Codes

Regular Colors

• \033[00;30m - Black
• \033[00;31m - Red
• \033[00;32m - Green
• \033[00;33m - Yellow
• \033[00;34m - Blue
• \033[00;35m - Magenta
• \033[00;36m - Cyan
• \033[00;37m - White

Bright/Bold Colors (Used in Default Statusline)

• \033[01;30m - Bright Black (Gray)
• \033[01;31m - Bright Red
• \033[01;32m - Bright Green
• \033[01;33m - Bright Yellow
• \033[01;34m - Bright Blue
• \033[01;35m - Bright Magenta
• \033[01;36m - Bright Cyan
• \033[01;37m - Bright White

Default Statusline Colors

The generated statusline uses these colors by default:

Customizing Colors

To customize colors in the statusline script, edit the printf statements:

Example: Change username to bright blue

# Original:
printf '\033[01;32m%s\033[00m' "$username"

# Modified:
printf '\033[01;34m%s\033[00m' "$username"

Example: Change path to yellow

# Original:
printf '\033[01;37m%s\033[00m' "$short_path"

# Modified:
printf '\033[01;33m%s\033[00m' "$short_path"

Testing Colors

Test color codes in terminal:

echo -e "\033[01;32mGreen\033[00m \033[01;36mCyan\033[00m \033[01;35mMagenta\033[00m"

Tips

1. Always reset: End each colored section with \033[00m to reset colors 2. Visibility: Bright colors (01;3X) are more visible than regular (00;3X) 3. Contrast: Choose colors that contrast well with your terminal background 4. Consistency: Use consistent colors for similar elements across your environment

Statusline Input JSON Schema

The statusline script receives a JSON object on stdin. This reference documents all known fields.

Top-Level Fields

{
  "session_id": "uuid",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/dir",
  "version": "2.1.121",
  "fast_mode": false,
  "exceeds_200k_tokens": false,
  "output_style": { "name": "default" },
  "model": {
    "id": "model-id-string",
    "display_name": "Human-Readable Model Name"
  },
  "workspace": {
    "current_dir": "/path/to/cwd",
    "project_dir": "/path/to/project",
    "added_dirs": ["/additional/dir"]
  },
  "cost": {
    "total_cost_usd": 1.0868,
    "total_duration_ms": 342863,
    "total_api_duration_ms": 282122,
    "total_lines_added": 0,
    "total_lines_removed": 0
  },
  "context_window": { ... },
  "effort": { "level": "max" },
  "thinking": { "enabled": true }
}

context_window Object (Key Fields)

{
  "context_window": {
    "context_window_size": 1000000,
    "used_percentage": 9,
    "remaining_percentage": 91,
    "total_input_tokens": 83320,
    "total_output_tokens": 5456,
    "current_usage": {
      "input_tokens": 29,
      "output_tokens": 163,
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 88832
    }
  }
}

Field Meanings

Computing Actual Context Usage

Correct formula:

current_context_used = current_usage.input_tokens
                     + current_usage.cache_read_input_tokens
                     + current_usage.cache_creation_input_tokens

This sum should approximately equal context_window_size * used_percentage / 100.

*Prefer `current_usage. summed.** It is correct on every Claude Code version (0 at session start, never null, never cumulative). total_input_tokens is equivalent on v2.1.132 and later but was session-cumulative before that and could exceed context_window_size. If you need to support older Claude Code versions, use current_usage`.

Model Context Window Sizes (Reference)

Always read context_window_size from the JSON — never hardcode it.

cost Object

Customization

How to modify the statusline beyond layout switching. Load this file when the user wants colors, custom segments, or to disable specific features.

Change colors (full layout)

Colors are ANSI escape codes in printf calls inside render_full(). See `color_codes.md` for the complete code reference.

Example — recolor the username from green to blue:

# In scripts/generate_statusline.sh, find this line in render_full:
printf '\033[01;32m%s\033[00m \033[01;36m(%s)\033[00m%s%s\n...' "$username" ...
#         ^^^^^^^^ green (32)

# Change to blue (34):
printf '\033[01;34m%s\033[00m \033[01;36m(%s)\033[00m%s%s\n...' "$username" ...

Standard color codes:

After editing, always verify with bash scripts/health_check.sh to confirm mock tests still pass.

Add custom segments (full layout)

Extend render_full() to add hostname, time, weather, or anything else.

Pattern:

render_full() {
    # ... existing code ...
    
    # Your new segment
    local hostname segment_color
    hostname=$(hostname -s)
    segment_color="\033[01;34m"   # blue
    
    # Add to the existing printf format string
    printf '\033[01;32m%s@%s\033[00m \033[01;36m(%s)\033[00m%s%s\n...' \
        "$username" "$hostname" "$model" "$cost_info" "$ctx_display"
    #          ^^^^^   ^^^^^^^^^ added
}

Pattern — time:

local now
now=$(date +%H:%M)
# Add %s and "$now" to the printf

Keep additions side-effect-free so health_check.sh mock tests remain deterministic. After editing, run bash scripts/health_check.sh.

Disable cost tracking (full layout)

Cost requires ccusage. If ccusage is not installed, cost_info is empty automatically — no edit needed, the segment silently disappears.

To skip the lookup entirely (saves ~50ms on each refresh):

In scripts/generate_statusline.sh, locate the cost block in render_full():

if command -v ccusage >/dev/null 2>&1; then
    # ... cache + ccusage logic ...
fi

Wrap or comment out the entire if block. Health check will still pass.

Switch to single-line full layout

The default full layout is multi-line (3 lines: header / path / git). To collapse it into a single line, edit the final printf in render_full():

# Three-line (default full):
printf '\033[01;32m%s\033[00m \033[01;36m(%s)\033[00m%s%s\n\033[01;37m%s\033[00m\n%s' \
    "$username" "$model" "$cost_info" "$ctx_display" "$short_path" "$git_info"

# Single-line full:
printf '\033[01;36m[%s]\033[00m \033[01;37m%s\033[00m %s%s | \033[01;32m$%s\033[00m' \
    "$model" "$short_path" "$git_info" "$ctx_display" "$cost"

Change ctx color thresholds

Default thresholds (full layout): green ≤50%, yellow 51–80%, red >80%.

To change, edit in render_full():

local ctx_color="\033[01;32m"   # green ≤50%
if [ "${ctx_pct_int:-0}" -gt 80 ]; then
    ctx_color="\033[01;31m"     # red >80%
elif [ "${ctx_pct_int:-0}" -gt 50 ]; then
    ctx_color="\033[01;33m"     # yellow 51-80%
fi

Adjust the 80 and 50 cutoffs to taste.

Where to put the env var setting

For CLAUDE_STATUSLINE_LAYOUT and CLAUDE_STATUSLINE_DEBUG to apply to Claude Code, the variables must be exported in the shell before Claude Code starts. Set them in:

• macOS / Linux: ~/.zshrc, ~/.bashrc, ~/.profile, or ~/.config/fish/config.fish
• Per-project: .envrc (with direnv)

Restart the shell or source the rc file, then start Claude Code.

Troubleshooting Decision Tree

When the statusline misbehaves, run the health check first — it covers most issues:

bash scripts/health_check.sh

If the health check passes but you still see an issue, walk the symptoms below.

---

Symptom 1: Statusline is blank or never updates

Most common root cause: the script is not executable. Claude Code runs the configured command and silently shows nothing if the exec fails. This is the single biggest source of "I configured it but nothing happens" reports.

Diagnose:

ls -la "$(jq -r '.statusLine.command' ~/.claude/settings.json | sed "s|^~|$HOME|; s|^bash ||")"

Look at the leftmost column. If it does not start with -rwx, the script is missing its executable bit.

Fix:

chmod +x ~/.claude/statusline.sh

(Substitute the actual path from your settings.json.)

Other possible causes:

• settings.json statusLine.command points to a path that no longer exists.

Run bash scripts/health_check.sh to confirm.

• The script's shebang references an interpreter that's not installed. Verify

with head -1 ~/.claude/statusline.sh — should be #!/usr/bin/env bash or similar.

• The script writes to stderr instead of stdout. Claude Code only displays

stdout. Pipe a mock stdin and inspect: echo '{}' | ~/.claude/statusline.sh.

---

Symptom 2: ctx: ... segment is missing or shows wrong numbers

Root cause A: `used_percentage` is `null` early in a session.

The Claude Code docs explicitly warn that context_window.used_percentage and remaining_percentage "may be null early in the session." If your script gates the ctx segment on these fields, the segment vanishes until the first real API response populates them. A naive // empty filter swallows the output entirely.

Fix: This skill's generate_statusline.sh computes used tokens from current_usage.input_tokens + cache_read_input_tokens + cache_creation_input_tokens, which is 0 (not null) at session start, so the ctx segment renders even before any real usage.

Root cause B: confusing `total_input_tokens` with current context.

In Claude Code v2.1.131 and earlier, total_input_tokens was a session-cumulative count and could exceed context_window_size. Using it as "current usage" shows percentages above 100% in long sessions.

Fix: Use current_usage.* summed (this skill's default). It always reflects the current context state regardless of Claude Code version.

Root cause C: `context_window_size` missing from JSON.

Some early versions or non-standard clients omit this field. The script then divides by zero (or skips the segment).

Diagnose:

export CLAUDE_STATUSLINE_DEBUG=1
# Send any message in Claude Code, then:
jq '.context_window' /tmp/.claude-statusline-last-stdin.json

If context_window_size is missing, your Claude Code is too old or running a non-standard runtime. Update Claude Code.

---

Symptom 3: I want token counts, not percentages

The default layout shows ctx: 108K / 1M (token counts only). If yours shows percentages, you are running the full layout.

Switch to minimal:

Remove this from your shell rc file:

export CLAUDE_STATUSLINE_LAYOUT=full

Or set it explicitly to minimal:

export CLAUDE_STATUSLINE_LAYOUT=minimal

Then start a new shell so Claude Code inherits the new env.

---

Symptom 4: Colors look wrong or render as literal escape codes

Diagnose:

echo '{"workspace":{"current_dir":"/tmp"},"model":{"display_name":"M"},"context_window":{"context_window_size":100000,"used_percentage":80,"current_usage":{"input_tokens":80000,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}' | \
  CLAUDE_STATUSLINE_LAYOUT=full ~/.claude/statusline.sh | cat -v

If you see ^[[01;33m instead of yellow text, your terminal is not interpreting ANSI escape codes.

Fix:

• Most modern terminals (iTerm2, Apple Terminal, Kitty, Windows Terminal,

WezTerm) support these by default. If yours doesn't, switch terminal.

• Claude Code itself renders the statusline output and supports ANSI colors,

so this issue is rare during actual use — only shows up when you pipe the script manually.

---

Symptom 5: Git status segment is missing (full layout)

Root cause A: You're not inside a git repository. Expected — git segment is silent outside repos.

Root cause B: git binary not installed.

Diagnose:

command -v git || echo "git not installed"
git -C "$PWD" rev-parse --git-dir 2>&1

Fix: Install git, or accept that the segment is hidden.

Root cause C: Permission errors reading .git/.

ls -la "$(git rev-parse --git-dir 2>/dev/null)" 2>&1 | head -3

---

Symptom 6: Cost segment is missing (full layout)

The cost segment depends on ccusage being installed and on PATH. It runs asynchronously with a 2-minute cache, so the first display after install is expected to lack it; the cache populates within 5–10 seconds.

Diagnose:

command -v ccusage || echo "ccusage not installed"
ccusage session --json --offline -o desc 2>&1 | head -20
ls -lh /tmp/claude_cost_cache_*.txt 2>/dev/null

Fix:

• Install ccusage: npm install -g ccusage (or see the ccusage repo for

current install instructions).

• Wait for the background fetch on first use.
• Force refresh: rm /tmp/claude_cost_cache_*.txt then trigger a statusline

update by sending any message in Claude Code.

For deeper details and offline data structure, see `ccusage_integration.md`.

---

Symptom 7: I edited the script but my changes have no effect

Claude Code reads the script every refresh, so live edits should take effect on the next statusline update (typically the next assistant message).

Diagnose:

# Confirm Claude Code actually runs your edited script:
export CLAUDE_STATUSLINE_DEBUG=1
# Then send a message in Claude Code and check the dump:
ls -la /tmp/.claude-statusline-last-stdin.json

If the dump's mtime updates after your message, the script is being executed. If your edits still have no effect, try bash health_check.sh to confirm the script being run is actually the one you edited (it might be a stale copy at a different path).

Possible mismatch: settings.json statusLine.command points to one path, but you edited a different file. The health check warns when these diverge.

---

Symptom 8: Script is slow (statusline appears with delay)

Diagnose:

time (echo '{"workspace":{"current_dir":"/tmp"},"model":{"display_name":"M"},"context_window":{"context_window_size":1000,"current_usage":{"input_tokens":0,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}' | ~/.claude/statusline.sh)

Should be well under 100ms. If much slower, suspect:

• `ccusage` blocking: Should be backgrounded by the script. Verify with

time ccusage session --json --offline -o desc | head -1.

• `git` slow on a large repo: Switch to minimal layout to skip git lookup.
• `python3` fallback hot path: Install jq (brew install jq).

---

When all else fails

Capture both real stdin and the script's actual output, then re-run health check:

export CLAUDE_STATUSLINE_DEBUG=1
# Send a message in Claude Code, wait 1 second, then:
bash scripts/health_check.sh
echo "---"
echo "Real stdin Claude Code sent:"
jq . /tmp/.claude-statusline-last-stdin.json
echo "---"
echo "Script output for that stdin:"
cat /tmp/.claude-statusline-last-stdin.json | ~/.claude/statusline.sh

The combination of health_check.sh results plus the captured stdin/output pair is enough evidence to diagnose virtually any issue.