statusline-customization

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 (master switch)
    "claudish_plan": true  // Provider plan bars when the session is routed via claudish
  },
  "icons": {
    "nerd_font": false     // Opt in to Nerd Font glyphs (RAM → 󰍛). Default OFF
  },
  "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
  "appearance": "auto",    // "auto" | "light" | "dark" — see Appearance below
  "wrap": "auto",          // "auto" wraps to the terminal width, "off" forces one line
  "max_lines": 0,          // Cap on wrapped rows; 0 means no cap
  "layout": "auto"         // "auto" | "aligned" | "compact" — see Wrapping below
}

All fields are optional. Missing fields use defaults shown above. sections and icons are independent groups — setting one never affects the other.

theme and appearance are orthogonal: theme picks the palette's character (default / minimal / neon / monochrome), appearance picks whether that palette is drawn for a light or a dark terminal.

Appearance

The statusline resolves light vs dark at render time, because the same colours cannot work on both. It follows the same six-step order as magus and tmux-setup, first hit wins:

1. appearance in this config, when set to light or dark (the script's own flag)
2. $STATUSLINE_APPEARANCE — per-pane override without touching the config (its own variable)
3. $TERM_THEME
4. OSC 11 probe — no step: the statusline child has no tty (stdin, stdout and stderr are pipes), so there is nowhere to send a background-colour query
5. COLORFGBG — inside tmux, the session-scope copy read via tmux show-environment; outside tmux, the $COLORFGBG environment variable
6. dark