statusline-customization

name	statusline-customization
description	Configuration reference and troubleshooting for the statusline plugin — sections, themes, bar widths, and script architecture
globs	["**/statusline*","**/.claude/settings.json","**/statusline-config.json"]

Statusline Customization Reference

Config File

Location: ~/.claude/statusline-config.json

Schema

{
  "sections": {
    "model": true,         // Model name (Opus/Sonnet/Haiku)
    "branch": true,        // Git branch name
    "worktree": true,      // Worktree indicator (wt:name)
    "cost": true,          // Session cost ($X.XX)
    "duration": true,      // Session duration (Xm Xs)
    "context_bar": true,   // Context window usage bar
    "plan_limits": true    // Plan limit bars with reset countdowns
  },
  "context_bar_width": 12, // Width of context bar in chars (8-20)
  "plan_bar_width": 10,    // Width of plan limit bar in chars (6-16)
  "theme": "default"       // Color theme name
}

All fields are optional. Missing fields use defaults shown above.

Sections Reference

Section	Color	Description
model	Cyan (bold)	Shortened model name with * prefix
branch	Green	Current git branch or short commit hash
worktree	Orange (bold)	wt:name — only shown when inside a linked worktree
cost	Yellow	Cumulative session cost in USD
duration	Magenta	Session duration in minutes/seconds
context_bar	Green→Red gradient	Visual bar + token count (90k/200k) + compaction indicator (⟳)
plan_limits	Teal→Red gradient	Dual bar: top=5h, bottom=7d plan usage with reset countdowns

Plan Limits Bar Characters

• █ — both 5h and 7d usage at this position
• ▀ — only 5h usage (top half)
• ▄ — only 7d usage (bottom half)
• - — empty (unused capacity)

Reset Countdown Format

After each percentage, a countdown shows when the limit resets:

• ↻1h40m — resets in 1 hour 40 minutes
• ↻3d12h — resets in 3 days 12 hours
• ↻now — resetting now

Example: █▄▄------- 5h:18% ↻1h40m 7d:35% ↻3d12h

Context Bar Token Count

After the percentage, a dim token count shows current/max context usage:

• 45% 90k/200k — 90k tokens used out of 200k window
• 72% 144k/200k — approaching limit
• Only shown when Claude Code provides token data in stdin

Compaction Detection

A bold magenta ⟳ appears after the token count when auto-compaction is detected:

• 25% 50k/200k ⟳ — compaction just happened (tokens dropped)
• The indicator appears for one render only, then disappears
• Detection works by caching total_input_tokens between renders; a drop means compaction occurred
• Cache file: ~/.claude/.statusline-token-cache

Themes

Theme	Description
default	Warm/cool ANSI palette — bright cyan, green, yellow, orange, red
monochrome	White and gray only — no colors
minimal	Muted dim ANSI colors (30-series) — subtle and low-contrast
neon	256-color bright variants — vivid and high-contrast

Script Architecture

Data Flow

1. Claude Code pipes JSON session data to stdin
2. Script reads config from ~/.claude/statusline-config.json
3. Extracts fields with jq
4. Detects git branch and worktree from cwd
5. Reads plan usage from non-blocking background cache
6. Renders ANSI-colored output to stdout

Non-Blocking API Cache

• Cache file: ~/.claude/.statusline-usage-cache.json
• TTL: 60 seconds
• Mechanism: Background subshell ( ... ) & fires API call; current render uses stale cache
• Token source: macOS Keychain (security find-generic-password -s "Claude Code-credentials")
• API endpoint: https://api.anthropic.com/api/oauth/usage

Input JSON Schema (from Claude Code)

{
  "model": { "display_name": "Claude Opus 4.6" },
  "cost": { "total_cost_usd": 1.23, "total_duration_ms": 180000 },
  "context_window": { "used_percentage": 45.2 },
  "cwd": "/path/to/project"
}

Troubleshooting

jq not found

The script requires jq for JSON parsing. Install with:

brew install jq

No plan limits showing

• Check if cache file exists: ls -la ~/.claude/.statusline-usage-cache.json
• Verify Keychain access: security find-generic-password -s "Claude Code-credentials" -w | head -c 20
• If Keychain prompts are denied, the API call silently fails — grant access when prompted
• Plan limits only show when both 5h and 7d utilization data are available

Config not taking effect

• Verify JSON syntax: jq . ~/.claude/statusline-config.json
• After changing config, the script picks it up on next render (no restart needed)
• To redeploy the script itself after a plugin update, run /statusline:install-statusline

Script not executable

chmod +x ~/.claude/statusline-command.sh
# or for project-level:
chmod +x .claude/statusline-command.sh

Reset countdown not showing

• Reset times come from the resets_at field in the usage API response
• If the field is missing from the API response, no countdown is shown
• Verify with: jq '.five_hour.resets_at, .seven_day.resets_at' ~/.claude/.statusline-usage-cache.json