statusline-customization

# Statusline Customization Reference ## Config File **Location:** `~/.claude/statusline-config.json` ### Schema ```json { "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) ```json { "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: ```bash 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 ```bash 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`