statusline-config

StatusLine Config

Customize ~/.claude/statusline-command.sh — segments, themes, and colors.

When NOT to Use

| Scenario | Use Instead | |----------|-------------| | Setting statusline for the first time (no customization needed) | Built-in statusline-setup agent (Claude Code agent type) — applies defaults automatically | | Editing settings.json directly | Manual edit — this skill manages statusline-command.sh, not settings.json | | Debugging Claude Code startup issues | /claude-health — config health check |

Segments

| Segment | JSON Field | Default | Notes | | ----------- | ------------------------------------- | ---------------- | ------------------------------------- | | Directory | workspace.current_dir | ON | Truncate deep paths: ~/.../last-dir | | Git branch | shell git | ON | --no-optional-locks, cache 5s | | Agent | agent.name | ON (conditional) | Show when present; color: C_MODEL | | Model | model.display_name + context_window.context_window_size | ON | Smart tier suffix: Opus 4.6 (1M) — auto-skip if display_name already contains context info | | Context % | context_window.remaining_percentage + context_window_size | ON | ctx 60% left (600k/1M) — Green >40%, Yellow 20-40%, Red <=20% | | Token Usage | context_window.total_input_tokens + total_output_tokens | ON (conditional) | {in}k/{out}k session cumulative; color: C_COST | | Cost | cost.total_cost_usd | ON | Show when >= $0.005, est $X.XX | | Rate Limits | rate_limits.five_hour.used_percentage + seven_day.used_percentage | ON (conditional) | 5h: 85% left · 7d: 82% left — displays remaining (100 - used); color thresholds match context %: Green >40%, Yellow 20-40%, Red <=20%; OAuth users only | | Worktree | worktree.name + worktree.branch | ON (conditional) | [WT:{name}] {branch} or [WT:{name}] if branch absent; replaces Directory + Git branch when present; color: C_BRANCH |

For full JSON schema, see [json-schema.md](references/json-schema.md).

Themes

| Theme | Type | Default | Notes | | ------------------ | --------- | ------- | ------------------------------------- | | ansi-default | ANSI 16 | ✅ | Safe fallback, works everywhere | | catppuccin-mocha | TrueColor | — | Recommended — pastel, WCAG AA >=4.5:1 | | dracula | TrueColor | — | Vibrant purple/pink accents | | nord | TrueColor | — | Arctic blue, muted tones | | none | — | — | No colors (NO_COLOR auto-triggers) |

Switch via: export CLAUDE_STATUSLINE_THEME=catppuccin-mocha

For complete token→hex mappings, see [themes.md](references/themes.md).

Semantic Tokens

Scripts use semantic tokens instead of hardcoded colors:

| Token | Role | Example | | ------------ | -------------------- | ------------------- | | C_CWD | Directory path | blue / sapphire | | C_BRANCH | Git branch name | magenta / mauve | | C_MODEL | Model display name | cyan / teal | | C_CTX_OK | Context >= 41% | green | | C_CTX_WARN | Context 21-40% | yellow | | C_CTX_BAD | Context <= 20% | red | | C_COST | Cost display | muted text | | C_ALERT | >200k token warning (legacy, segment removed) | orange/peach + bold | | C_SEP | Pipe separator \| | dim/overlay | | C_MUTED | Secondary info | subtext | | C_TEXT | General text | foreground | | C_RESET | Reset all formatting | \033[0m |

Workflow

No args → Apply best-practice defaults (all ON segments + ansi-default theme). Go to step 4.

Theme change (e.g. "use catppuccin-mocha", "switch to dracula") → Read [themes.md](references/themes.md), apply requested theme. Go to step 4. Aliases: catppuccin → catppuccin-mocha.

Custom requests (e.g. "add cost", "remove git", "no colors") → Interactive flow:

1. Read current script: cat ~/.claude/statusline-command.sh
2. Ask segments to enable/disable (AskUserQuestion multiSelect)
3. Ask theme preference (AskUserQuestion with theme options)
4. Generate script following Script Rules + selected theme from [themes.md](references/themes.md)
5. Write to ~/.claude/statusline-command.sh
6. Verify: echo '{"model":{"display_name":"Opus 4.6"},"workspace":{"current_dir":"/tmp/test"},"context_window":{"remaining_percentage":55},"cost":{"total_cost_usd":0.42},"exceeds_200k_tokens":false}' | ~/.claude/statusline-command.sh

Script Rules

• Shebang: #!/bin/sh (POSIX)
• Read stdin: input=$(cat)
• Parse JSON: jq -r '.field // fallback'
• Theme from env: theme="${CLAUDE_STATUSLINE_THEME:-ansi-default}"
• NO_COLOR: [ -n "${NO_COLOR:-}" ] && theme="none"
• Theme aliases: catppuccin → catppuccin-mocha
• Invalid theme: fallback to ansi-default
• Color output: printf "%b" for ANSI/TrueColor, printf "%s" for none
• TrueColor format: \033[38;2;R;G;Bm (24-bit foreground)
• Git: git --no-optional-locks -C "$dir"
• Git cache: /tmp/claude-statusline-git-cache-$(id -u), 5s TTL, stat -f %m (macOS) / stat -c %Y (Linux)
• CWD truncation: depth >2 → ~/.../basename
• Cost: only when >= 0.005, format est $X.XX
• Alert style: C_ALERT + bold (\033[1m) to distinguish from C_CTX_BAD
• Token format: %.1fk via awk (e.g. 8500 → 8.5k); values < 1000 show raw number
• Tier format: >=1M → (1M), >=1000 → ({N}k), else raw; used for model suffix + context absolute
• Model tier suffix: append (1M) or (200k) from context_window_size; skip if display_name already contains context, 1M, or 200k
• Context absolute: ctx 60% left (600k/1M) — remaining tokens calculated from remaining_percentage * context_window_size / 100
• Sanitize free-text: strip control chars (tr -d '[:cntrl:]') + truncate 30 chars for agent.name, worktree.name, worktree.branch
• Worktree replace: when worktree.name present, replace Directory + Git branch with [WT:{name}] {branch} (or [WT:{name}] if worktree.branch absent — hook-based worktrees)
• Rate limits: show when rate_limits present; display remaining % (100 - used_percentage) with "left" suffix; format 5h: {rem}% left · 7d: {rem}% left; color by worst remaining — Green >40% (C_CTX_OK), Yellow 20-40% (C_CTX_WARN), Red <=20% (C_CTX_BAD); thresholds match context %; OAuth users only
• Rate limits resets_at: extracted but not displayed in v1 (too verbose for statusline)
• Render order (normal): Directory | Git branch | Agent? | Model (tier) | Context % (abs) · Token Usage? · Cost? · Rate Limits?
• Render order (worktree): [WT:name] branch | Agent? | Model (tier) | Context % (abs) · Token Usage? · Cost? · Rate Limits?

Script Structure

#!/bin/sh
input=$(cat)
# ... extract JSON fields ...

theme="${CLAUDE_STATUSLINE_THEME:-ansi-default}"
[ -n "${NO_COLOR:-}" ] && theme="none"

case "$theme" in
  catppuccin|catppuccin-mocha) # set C_* tokens with TrueColor values ;;
  dracula)          # ... ;;
  nord)             # ... ;;
  none)             # all C_* = "" ;;
  *)                # ansi-default: ANSI 16 colors ;;
esac

# ... build output using C_* tokens ...
if [ "$theme" = "none" ]; then
  printf "%s" "$out"
else
  printf "%b" "$out"
fi

Example Output

Normal mode (1M context):
~/.../my-project | feat/auth | Opus 4.6 (1M) | ctx 60% left (600k/1M) · 85.0k/12.0k · est $18.12

Normal mode (200k context):
~/.../my-project | main | Sonnet 4.6 (200k) | ctx 30% left (60k/200k) · 120.0k/8.0k · est $3.50

With agent:
~/.../my-project |