# 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,
"autocompact_buffer_size": 45000
},
"quota": {
"enabled": true,
"show_time_remaining": true,
"cache_ttl": 0
},
"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
| `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`
---
### `sections.git` - Git Information
| `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
---
### `sections.model` - Claude Model Name
| `enabled` | boolean | `true` | Show Claude model name (e.g., "Sonnet 4.5") |
| `show_output_style` | boolean | `false` | Display output style mode (default/verbose) |
| `show_thinking_mode` | boolean | `true` | Show thinking mode indicator |
**Example:**
```json
"model": {
"enabled": true,
"show_output_style": false,
"show_thinking_mode": true
}
```
Shows: `Sonnet 4.5 (thinking)` when thinking mode is active
**Note:** Thinking mode is read from `~/.claude/settings.json` - it's omitted when enabled, present as `false` when disabled.
---
### `sections.context` - Context Usage
| `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 (110k/200k) vs percentage only |
| `autocompact_buffer_size` | integer | `45000` | Token threshold for switching to percentage display |
**Display modes:**
- `show_token_counts: true` → `110k/200k` (detailed)
- `show_token_counts: false` → `55%` (compact)
- `show_decimals: true` → `55.2%`
- `show_decimals: false` → `55%`
**Example - Compact with decimals:**
```json
"context": {
"enabled": true,
"show_decimals": true,
"show_token_counts": false,
"autocompact_buffer_size": 45000
}
```
Result: `87.5%`
---
### `sections.quota` - Usage Quota (5h/7d)
| `enabled` | boolean | `true` | Show quota limits (5h/7d percentages + timers) |
| `show_time_remaining` | boolean | `true` | Show reset timers (false = percentages only) |
| `cache_ttl` | integer | `0` | Cache quota API responses (seconds). 0 = always fetch fresh |
**Display modes:**
- `show_time_remaining: true` → `5h: 45% (3h 12m)` (with timer)
- `show_time_remaining: false` → `5h: 45%` (compact)
#### How Statusline Updates Work
Claude Code triggers statusline updates **when conversation messages update**, but throttles them to **at most every 300ms** to maintain UI responsiveness. On each trigger:
1. Claude Code passes JSON data via stdin (model, context, workspace info)
2. Statusline binary processes the data
3. First line of stdout becomes your statusline
**With `cache_ttl: 0` (default):**
- 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 and more API calls
**With `cache_ttl: 60` (cached):**
- 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, but data may be up to 60s stale
#### 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
**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 in memory only and resets when Claude Code restarts.
---
### `sections.cost` - API Cost
| `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
| `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 |
**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: `(default | thinking)` instead of `(default, thinking)`
- 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, "autocompact_buffer_size": 45000 },
"quota": { "enabled": false, "show_time_remaining": true, "cache_ttl": 0 },
"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 },
"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 },
"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:
| `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]
}
```