Claude Statusline

A customizable powerline status line for Claude Code with 3 visual styles, 4 color themes, and comprehensive session metrics — all in a clean 2-line layout.

Zero external dependencies. Python 3.8+ stdlib only.

Styles

Powerline

Classic powerline arrows with colored segments flowing left to right.

 Documents/Career  main ●  Sonnet 4  fix-auth 
████████░░ 80% │ 5h: ████ 23% 7d: ████ 41% │ in:45k out:12k c:13k │ +150 -30 │ 5m

Capsule

Rounded pill-shaped segments with soft edges.

 Documents/Career   main ●   Sonnet 4   fix-auth 
████████░░ 80% │ 5h: ████ 23% 7d: ████ 41% │ in:45k out:12k c:13k │ +150 -30 │ 5m

TUI

Bordered box using Unicode box-drawing characters (no Nerd Font required).

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Documents/Career │ main ● │ Sonnet 4 │ fix-auth                                ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ ████████░░ 80% │ 5h: ████ 23% 7d: ████ 41% │ in:45k out:12k c:13k │ +150 -30 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Themes

| Theme | Style | |-------|-------| | Dark | Warm browns, cool blues, cyan accents | | Nord | Arctic blue palette based on Nord | | Tokyo Night | Purple/blue palette based on Tokyo Night | | Gruvbox | Retro warm palette based on Gruvbox |

Quick Install

git clone https://github.com/demigod97/claude-statusline.git
cd claude-statusline
./setup.sh

With style and theme options:

./setup.sh --style capsule --theme tokyonight

Via npx

npx @raavalabs/claude-statusline

Manual Install

# Create directory
mkdir -p ~/.claude/statusline

# Copy files
cp powerline.py ~/.claude/statusline/
cp config.default.json ~/.claude/statusline/config.json

# Add to Claude Code settings (~/.claude/settings.json)
# Add this key to the top-level object:
#   "statusLine": {
#     "type": "command",
#     "command": "python3 ~/.claude/statusline/powerline.py",
#     "refreshInterval": 5
#   }

What It Shows

Line 1 — Identity

| Segment | Description | Example | |---------|-------------|---------| | Directory | Last N levels of working directory | Documents/Career | | Git | Branch, dirty, ahead/behind, staged/modified/untracked | main ● ↑2 +1 ~3 ?2 | | Model | Current Claude model | Sonnet 4 | | Session | Session name (if set) | fix-auth-bug |

Line 2 — Metrics

| Segment | Description | Example | |---------|-------------|---------| | Context | Context window usage bar + percentage | ████████░░ 80% | | Rate Limits | 5-hour and 7-day usage with mini bars | 5h: ████ 23% 7d: ██░░ 41% | | Tokens | Input, output, and cache token counts | in:45k out:12k c:13k | | Lines | Lines added/removed in session | +150 -30 | | Vim Mode | Current vim mode (when vim is enabled) | NORMAL | | Duration | Session duration | 5m or 1h 23m |

Color Thresholds

Context and rate limit bars change color based on usage:

| Usage | Color | |-------|-------| | < 50% | Green | | 50-75% | Yellow | | 75-90% | Orange | | > 90% | Red |

Configuration

Edit ~/.claude/statusline/config.json:

{
  "style": "powerline",
  "theme": "dark",
  "path_levels": 2,
  "bar_width": 10
}

| Key | Values | Default | Description | |-----|--------|---------|-------------| | style | powerline, capsule, tui | powerline | Visual style | | theme | dark, nord, tokyonight, gruvbox | dark | Color theme | | path_levels | 1-5 | 2 | Directory depth shown | | bar_width | 4-20 | 10 | Width of progress bars in characters |

Changes take effect on the next refresh (every 5 seconds).

Requirements

• Python 3.8+ (uses only stdlib — no pip install needed)
• Claude Code installed and running
• Nerd Font (required for powerline and capsule styles; TUI works without)

Font Setup

The powerline and capsule styles use Nerd Font glyphs (arrows, rounded caps, git branch icon). Install a patched Nerd Font and configure your terminal to use it.

Recommended: JetBrains Mono Nerd Font

Quick install:

# macOS
brew install --cask font-jetbrains-mono-nerd-font

# Linux (Arch)
sudo pacman -S ttf-jetbrains-mono-nerd

# Windows (Scoop)
scoop bucket add nerd-fonts && scoop install JetBrainsMono-NF

Then set the font in your terminal settings. See fonts/FONTS.md for detailed platform-specific instructions.

How It Works

1. Claude Code pipes JSON session data to the script via stdin every 5 seconds
2. The script parses model info, context window, rate limits, cost, git status, etc.
3. Git status is cached per-session in /tmp files with a 5-second TTL and atomic writes
4. Output is rendered with ANSI truecolor (24-bit) escape codes
5. The terminal displays the 2-line (or 5-line for TUI) status bar

stdin JSON Shape

{
  "model": { "display_name": "Sonnet 4" },
  "cwd": "/home/user/project",
  "context_window": {
    "used_percentage": 45,
    "current_usage": {
      "input_tokens": 45000,
      "output_tokens": 12000,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 8000
    }
  },
  "cost": {
    "total_duration_ms": 300000,
    "total_lines_added": 150,
    "total_lines_removed": 30
  },
  "rate_limits": {
    "five_hour": { "used_percentage": 23 },
    "seven_day": { "used_percentage": 41 }
  },
  "session_name": "fix-auth-bug",
  "vim": { "mode": "NORMAL" },
  "transcript_path": "/home/user/.claude/sessions/abc123.jsonl"
}

Uninstall

./setup.sh --uninstall

Or manually:

rm -rf ~/.claude/statusline
# Then remove the "statusLine" key from ~/.claude/settings.json

Platform Support

| Platform | Status | |----------|--------| | Linux | Fully supported | | macOS | Fully supported | | WSL2 | Fully supported (use Windows Terminal with Nerd Font) | | Windows (Git Bash) | Supported (requires Python 3 in PATH) |

Troubleshooting

Status line not showing

1. Check that ~/.claude/settings.json has the statusLine config
2. Verify Python 3 works: python3 --version
3. Test manually: echo '{}' | python3 ~/.claude/statusline/powerline.py
4. Restart Claude Code

Broken glyphs / boxes instead of arrows

Install a Nerd Font and set it as your terminal font. See fonts/FONTS.md.

Or switch to TUI style which uses only Unicode box-drawing characters:

# Edit ~/.claude/statusline/config.json
{"style": "tui", "theme": "dark", "path_levels": 2, "bar_width": 10}

Git info not showing

• Make sure you're in a git repository
• Check that git is in PATH: which git
• Git status is cached for 5 seconds — changes may take a moment to appear

Colors look wrong

Your terminal must support truecolor (24-bit). Most modern terminals do:

• Windows Terminal, iTerm2, Alacritty, Kitty, WezTerm, GNOME Terminal (3.24+)

Test: echo -e "\x1b[38;2;255;100;0mTruecolor test\x1b[0m" — should show orange text.

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Test with: npm test (or pipe JSON manually)
4. Submit a PR

Adding a Theme

Add a new entry to the THEMES dict in powerline.py. Each theme needs colors for: dir, git, model, session, context, rate, tokens, lines, vim, duration.

Adding a Style

Add a new render_<style>_line() function and wire it into the main() function's style dispatch.

License

MIT - Wihitha Deshan (Demi) Thathsara