| 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,
"branch": true,
"worktree": true,
"cost": true,
"duration": true,
"context_bar": true,
"plan_limits": true
},
"context_bar_width": 12,
"plan_bar_width": 10,
"theme": "default"
}
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
- Claude Code pipes JSON session data to stdin
- Script reads config from
~/.claude/statusline-config.json
- Extracts fields with
jq
- Detects git branch and worktree from
cwd
- Reads plan usage from non-blocking background cache
- 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
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