# Configuration Reference
Complete reference for all configuration options in `settings.json` and `colors.json`.
## 📂 Configuration Files Location
Configuration files are automatically generated on first run:
- `~/.claude/statusline/settings.json` - Feature toggles and settings
- `~/.claude/statusline/colors.json` - Color customization
## ⚙️ settings.json Reference
### Structure Overview
The configuration is organized into two main categories:
- **`sections`** - Enable/disable and configure individual statusline sections
- **`display`** - Overall display and layout settings
### Complete Default Configuration
```json
{
"sections": {
"cwd": {
"enabled": true,
"full_path": true,
"show_username": false
},
"git": {
"enabled": true,
"show_repo_name": false,
"show_diff_stats": true
},
"model": {
"enabled": true,
"show_output_style": false,
"show_thinking_mode": true
},
"context": {
"enabled": true,
"show_decimals": false,
"show_token_counts": true,
"display_mode": "used"
},
"quota": {
"enabled": true,
"show_time_remaining": true,
"cache_ttl": 60
},
"cost": {
"enabled": false,
"show_durations": true
}
},
"display": {
"multiline": true,
"default_terminal_width": 120,
"use_powerline": false,
"segment_separator": "",
"details_separator": ", ",
"section_padding": 1,
"show_background": true
}
}
```
---
## 📋 Sections Configuration
### `sections.cwd` - Current Working Directory
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Show current working directory |
| `full_path` | boolean | `true` | Show full path (true) or just directory name (false) |
| `show_username` | boolean | `false` | Prefix path with username@ |
**Example:**
```json
"cwd": {
"enabled": true,
"full_path": false,
"show_username": true
}
```
Shows: `user@project` instead of `/Users/user/dev/project`
**Automatic details from Claude Code:**
- When you expand workspace scope with `/add-dir`, the CWD section can append `(+N dirs)`.
- When Git information is unavailable but Claude Code provides worktree metadata, the CWD section can append `(wt: name)`.
---
### `sections.git` - Git Information
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Show git branch and status |
| `show_repo_name` | boolean | `false` | Display repository name alongside branch |
| `show_diff_stats` | boolean | `true` | Show uncommitted changes as (+added \| -removed) |
**Example:**
```json
"git": {
"enabled": true,
"show_repo_name": true,
"show_diff_stats": true
}
```
Shows: `statusline [dev] (+150 | -25)` with repo name and diff stats
**Worktree note:** In `--worktree` sessions, the git section may append a compact worktree label such as `(wt: feature-a)` when Claude Code provides worktree metadata and it adds information beyond the current branch name.
---
### `sections.model` - Claude Model Name
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Show Claude model name (for example, `Sonnet 4.6`) |
| `show_output_style` | boolean | `false` | Display the legacy output style name when Claude Code provides one |
| `show_thinking_mode` | boolean | `true` | Show reasoning detail (`effort: level` or `thinking`) from the payload, falling back to Claude settings |
**Example:**
```json
"model": {
"enabled": true,
"show_output_style": false,
"show_thinking_mode": true
}
```
Shows: `Sonnet 4.6 (Learning)` or `Opus 4.6 (effort: medium)` when those details are available
**Note:** Output style is treated as legacy metadata because Claude Code no longer centers the UX around changing it mid-session. Reasoning details are read from the statusline payload first — `effort.level` (shows `effort: low|medium|high|xhigh|max`) or `thinking.enabled` (shows `thinking`) — so live `/effort` changes are reflected. If the payload omits them, the statusline falls back to `~/.claude/settings.json` (`effortLevel` or `alwaysThinkingEnabled`). Missing data is treated as unknown and omitted.
---
### `sections.context` - Context Usage
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Show context usage information |
| `show_decimals` | boolean | `false` | Show decimal percentages (87.5%) vs integers (87%) |
| `show_token_counts` | boolean | `true` | Display actual token numbers when Claude Code provides the context window size |
| `display_mode` | string | `"used"` | What to display: `"used"` (how much used) or `"remaining"` (how much left) |
**Modern Claude Code integration:**
Current Claude Code releases provide exact `used_percentage` and `remaining_percentage` values directly. The statusline will:
- Display exact percentages without the `~` prefix (e.g., `ctx: 55%`)
- Automatically use the correct percentage based on `display_mode`
- Fall back to calculated values with `~` prefix only when Claude Code does not provide direct percentages but does provide enough data to compute them
- Skip fake token totals when Claude Code omits the real context window size
**Display modes:**
- `display_mode: "used"` → Shows how much context is used (default)
- `display_mode: "remaining"` → Shows how much context is left
- `show_token_counts: true` → `55% (125k/1000k)` when the context window size is known
- `show_token_counts: false` → `55%` (compact)
- `show_decimals: true` → `55.5%`
- `show_decimals: false` → `55%`
**Large-context note:** On 1M-context sessions, the statusline uses the real `context_window_size` sent by Claude Code. If the size is missing, it shows the percentage only and avoids falling back to a fake `200k` total.
**Example - Show remaining context:**
```json
"context": {
"enabled": true,
"show_decimals": false,
"show_token_counts": false,
"display_mode": "remaining"
}
```
Result: `ctx: 45%` (showing 45% remaining)
---
### `sections.quota` - Usage Quota (5h/7d)
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Show quota limits (5h/7d percentages + timers) |
| `show_time_remaining` | boolean | `true` | Show reset timers (false = percentages only) |
| `cache_ttl` | integer | `60` | Cache OAuth usage-endpoint responses (seconds). `0` is supported for always-fresh polling, but higher values are safer and recommended |
**Display modes:**
- `show_time_remaining: true` → `5h: 45% (3h 12m)` (with timer)
- `show_time_remaining: false` → `5h: 45%` (compact)
#### How Quota Data Is Obtained
Since v1.2.10, quota is read **directly from the Claude Code payload** (`rate_limits.five_hour` / `rate_limits.seven_day`) whenever Claude Code sends it (Claude.ai Pro/Max subscribers, after the first API response). This path makes **no network calls at all** — the `cache_ttl` and OAuth usage endpoint only apply to the fallback path used when `rate_limits` is absent (API-key users or older Claude Code).
**With `cache_ttl: 60` (recommended default) on the fallback path:**
- First call fetches from API (~100-300ms)
- Subsequent calls within 60s read from cache (<1ms)
- After 60s, fetches fresh data again
- **Result**: Much faster renders, fewer API calls, and lower risk of usage-endpoint rate limits
**With `cache_ttl: 0` (advanced / always fresh):**
- Every statusline update (max 300ms interval) fetches fresh quota from API
- **API call time**: ~100-300ms per fetch
- **Result**: Most accurate quota data, but slower renders, more API calls, and higher risk of rate limiting
#### When to Use Cache TTL
**Use `cache_ttl: 0` (no cache) when:**
- You need real-time quota accuracy
- You rarely hit quota limits
- Statusline render speed is not a concern
- You accept the higher risk of usage-endpoint throttling
**Use `cache_ttl: 30-60` when:**
- You want faster statusline updates
- You're working in long sessions with frequent message updates
- You don't need exact real-time quota percentages
- You want to reduce API load
**Use `cache_ttl: 120-300` when:**
- Maximum performance is priority
- You're on slow/metered network connections
- You're well below quota limits and just want occasional checks
**Example - Balanced performance:**
```json
"quota": {
"enabled": true,
"show_time_remaining": true,
"cache_ttl": 60
}
```
Result: `5h: 45% (3h 12m) | 7d: 12% (4d 2h)` (quota cached for 60 seconds)
**Performance Impact:**
- Cache hit: <1ms (instant)
- Cache miss (API fetch): ~100-300ms (network dependent)
- API calls saved: With `cache_ttl: 60` and active conversation, saves ~10-20 API calls per minute
**Note:** Quota cache is stored on disk at `~/.claude/statusline/quota_cache.json` and reused until it expires.
---
### `sections.cost` - API Cost
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `false` | Show API cost for current session (Pro plan only) |
| `show_durations` | boolean | `true` | Display response time statistics |
**Example:**
```json
"cost": {
"enabled": true,
"show_durations": true
}
```
Shows: `$0.25 (2m 5s | api: 8s)` with cost and duration stats
---
## 🎨 Display Configuration
### `display` - Layout & Styling
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `multiline` | boolean | `true` | Wrap to multiple lines if terminal is narrow |
| `default_terminal_width` | integer | `120` | Assumed width when terminal size cannot be detected |
| `use_powerline` | boolean | `false` | Use Powerline arrows () between sections. Requires Powerline-compatible font. |
| `segment_separator` | string | `""` | Custom separator between sections (when `use_powerline: false`). Empty by default (colors only). Examples: `" \| "`, `" / "`, `" · "`, `" • "` |
| `details_separator` | string | `", "` | Separator within details parentheses. Examples: `", "`, `" \| "`, `" • "` |
| `section_padding` | integer | `1` | Number of spaces around section content |
| `show_background` | boolean | `true` | Show background colors for sections. When `false`, sections render as text-only and Powerline arrows fall back to plain separators |
**Note:** The Powerline arrow character () is hardcoded and not user-configurable.
### Multiline Mode
When `multiline: true`:
- All enabled sections are displayed across multiple lines if needed
- No sections are dropped based on terminal width
- Useful for vertical status displays or when you always want full info
When `multiline: false`:
- Sections are dropped based on priority when terminal is narrow
- Priority order (low to high): cost → quota → context → model → git → cwd
- Better for horizontal single-line displays
### Separator Modes
**No Separator** (default - `segment_separator: ""`):
```
~/project [dev] Sonnet 4.5 110k/200k 5h: 45%
```
Sections distinguished by colors only.
**Custom Separator** (`use_powerline: false` with custom separator):
```json
"display": {
"use_powerline": false,
"segment_separator": " | "
}
```
Result: `~/project | [dev] | Sonnet 4.5 | 110k/200k`
**Powerline Arrows** (`use_powerline: true`):
```json
"display": {
"use_powerline": true
}
```
Result: ` ~/project [dev] Sonnet 4.5 110k/200k `
Requires a [Powerline-patched font](https://github.com/powerline/fonts). The arrow character () is hardcoded.
### Details Separator
Controls the separator within detail parentheses:
```json
"details_separator": " | "
```
Results in:
- Git: `(+150 | -25)` instead of `(+150, -25)`
- Model: `(Learning | effort: medium)` instead of `(Learning, effort: medium)`
- Cost: `(2m 5s | api: 8s)` instead of `(2m 5s, api: 8s)`
### Recommended Separators
**Segment separators:**
- `" | "` - Pipe (classic)
- `" / "` - Slash
- `" · "` - Middle dot / interpunct
- `" • "` - Bullet
- `" "` - Just space
- `""` - No separator (default, colors only)
**Details separators:**
- `", "` - Comma (default)
- `" | "` - Pipe
- `" • "` - Bullet
- `" · "` - Middle dot
---
## 🎯 Common Configuration Patterns
### Minimal - Essential Info Only
```json
{
"sections": {
"cwd": { "enabled": true, "full_path": false, "show_username": false },
"git": { "enabled": true, "show_repo_name": false, "show_diff_stats": false },
"model": { "enabled": false, "show_output_style": false, "show_thinking_mode": true },
"context": { "enabled": true, "show_decimals": false, "show_token_counts": false, "display_mode": "used" },
"quota": { "enabled": false, "show_time_remaining": true, "cache_ttl": 60 },
"cost": { "enabled": false, "show_durations": true }
},
"display": {
"multiline": false,
"segment_separator": " | "
}
}
```
Result: `project | [dev] | 55%`
### Compact Multiline - All Info, No Details
```json
{
"sections": {
"cwd": { "enabled": true, "full_path": true, "show_username": false },
"git": { "enabled": true, "show_repo_name": false, "show_diff_stats": false },
"model": { "enabled": true, "show_output_style": false, "show_thinking_mode": true },
"context": { "enabled": true, "show_decimals": false, "show_token_counts": false, "display_mode": "used" },
"quota": { "enabled": true, "show_time_remaining": false, "cache_ttl": 60 },
"cost": { "enabled": true, "show_durations": false }
},
"display": {
"multiline": true,
"segment_separator": ""
}
}
```
Result: All sections shown, compact format (no details, no timers).
### Detailed Everything with Powerline
```json
{
"sections": {
"cwd": { "show_username": true },
"git": { "show_repo_name": true, "show_diff_stats": true },
"model": { "show_output_style": true, "show_thinking_mode": true },
"context": { "show_decimals": true, "show_token_counts": true, "display_mode": "used" },
"quota": { "show_time_remaining": true },
"cost": { "enabled": true, "show_durations": true }
},
"display": {
"use_powerline": true,
"details_separator": " | "
}
}
```
Shows full details with Powerline arrows and pipe separators in details.
---
## 🔄 Applying Changes
After modifying `settings.json`:
1. Save the file
2. Configuration changes are **automatically applied** - no restart needed!
3. The statusline re-reads config files on each render
---
## 💡 Tips
- Use `show_token_counts: false` for cleaner, more compact displays
- Combine `multiline: true` with compact settings to show everything
- Set `quota.cache_ttl: 60` if quota updates feel slow
- Use empty `segment_separator: ""` to rely on colors for section distinction
- `show_decimals: true` is useful when tracking context usage precisely
- Run `/customize-statusline` for an interactive configuration wizard
---
## 🎨 Color Customization
See **[colors.json documentation](#)** below for complete color reference.
---
# 🎨 colors.json Reference
### Complete Default Configuration
```json
{
"separator": [65, 65, 62],
"cwd": {
"background": [217, 119, 87],
"foreground": [38, 38, 36],
"details": [65, 65, 62]
},
"git": {
"background": [38, 38, 36],
"foreground": [217, 119, 87],
"details": [130, 129, 122]
},
"model": {
"background": [217, 119, 87],
"foreground": [38, 38, 36],
"details": [65, 65, 62]
},
"context": {
"background": [38, 38, 36],
"foreground": [217, 119, 87],
"details": [130, 129, 122]
},
"quota_5h": {
"background": [217, 119, 87],
"foreground": [38, 38, 36],
"details": [65, 65, 62]
},
"quota_7d": {
"background": [38, 38, 36],
"foreground": [217, 119, 87],
"details": [130, 129, 122]
},
"cost": {
"background": [217, 119, 87],
"foreground": [38, 38, 36],
"details": [65, 65, 62]
}
}
```
### Color Format
All colors are RGB arrays: `[red, green, blue]` with values 0-255.
**Transparency:** Use `null` instead of an array to make a background transparent:
```json
"cwd": {
"background": null,
"foreground": [255, 255, 255],
"details": [128, 128, 128]
}
```
### Section Colors
Each section has three color properties:
| Property | Description | Used For |
|----------|-------------|----------|
| `background` | Background color | Section background (or `null` for transparent) |
| `foreground` | Foreground color | Main text content |
| `details` | Details color | Secondary text (details in parentheses) |
### Color Sections
- `separator` - Color of the separator character/arrow (RGB only, not an object)
- `cwd` - Current working directory
- `git` - Git branch and diff stats
- `model` - Model name and details
- `context` - Context usage info
- `quota_5h` - 5-hour quota display
- `quota_7d` - 7-day quota display
- `cost` - Session cost display
### Examples
**High Contrast:**
```json
"cwd": {
"background": [0, 0, 0],
"foreground": [255, 255, 255],
"details": [128, 128, 128]
}
```
**Transparent Background:**
```json
"git": {
"background": null,
"foreground": [100, 200, 100],
"details": [50, 100, 50]
}
```
**Blue Theme:**
```json
"model": {
"background": [30, 60, 120],
"foreground": [220, 230, 255],
"details": [100, 140, 200]
}
```