Claude Code Status Line

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

Dark	Light

English | 繁體中文

Installation

curl -fsSL https://raw.githubusercontent.com/tzengyuxio/claude-statusline/main/install.sh | bash

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

Manual installation

1. Download the script:

curl -o ~/.claude/statusline-command.sh \
  https://raw.githubusercontent.com/tzengyuxio/claude-statusline/main/statusline-command.sh
chmod +x ~/.claude/statusline-command.sh

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

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline-command.sh",
    "padding": 1
  }
}

3. Restart Claude Code.

What You See

Line 1 — AI Status & Usage

Model │ Context Bar 28% │ $0.42 │ 5h 45% ↺ 4h27m │ 7d 12% ↺ 5d2h

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

my-project │ main +2 ~1 ?3 │ .venv (3.12) │ NORMAL

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:

export STATUSLINE_THEME=light  # or: dark, auto (default)

Credits

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

License

MIT