claude-statusline

Claude Code Status Line

A two-line status line for Claude Code. Shows what matters, skips what doesn't.

English | 繁體中文

Installation

Then restart Claude Code. Requires bash 4.0+, jq, git, and a Nerd Font.

Manual installation

1. Download the script:

2. Add to ~/.claude/settings.json:

3. Restart Claude Code.

What You See

Line 1 — AI Status & Usage

Model name, context progress bar (16 segments), session cost, 5h/7d API quota with reset countdown. A red alert badge appears at 90%+ context usage.

Line 2 — Workspace

Directory, git branch + file counts, Python venv (when detected), vim mode (when enabled).

All percentages use traffic-light coloring: green (0–49%), yellow (50–79%), red (80%+).

Design Philosophy

- Useful first, pretty second — if it doesn't affect your next action, it's not on the status line
- Quiet by default — optional segments (venv, vim mode) only show up when relevant
- Glanceable — two lines, color-coded, no reading required
- Fast — ~30ms render via single jq pass, single git status, and background-cached API calls

Customization

Edit statusline-command.sh:

- BAR_SEGMENTS — progress bar segments (default: 16)
- CACHE_TTL — API quota refresh interval in seconds (default: 60)
- pct_color() — color thresholds
- ICON_* — swap with your preferred Nerd Font glyphs

Dark / Light Mode

The status line auto-detects your terminal background:

1. macOS system appearance — reads AppleInterfaceStyle
2. COLORFGBG — set by some terminals (iTerm2, rxvt, etc.)
3. Fallback — defaults to dark

To override, set STATUSLINE_THEME before launching Claude Code:

Credits

Inspired by claude-powerline, steipete, keremkesgin, coffeewhistle, and Freek Van der Herten.

License

MIT