Statusline Customization Reference Skill

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

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
# 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

Agent Skills: Statusline Customization Reference

Install this agent skill to your local

Skill Files