Claude Code CLI Status Line

Example values for illustrating the color stages.

What is it?

A two-line, colored status line for the Claude Code CLI that shows all relevant session data at a glance:

• the current model (color-coded by type)
• the effort level
• thinking mode status
• context usage and token count
• rate limits for both the 5-hour and 7-day windows
• the working directory
• the active git branch
• the active worktree (if applicable)

Each metric can be shown as text, a coloured bar, both, or hidden.
Colors automatically shift from green → yellow → red as configured thresholds are crossed, making critical states immediately visible without interrupting Claude's output.

Every segment can be prefixed with either:

• a compact emoji => 🤖 | 💪 | 🧠 | 📦 | 🎫 | ...
• a word label => model | effort | thinking | ctx | ...
• both => 🤖 model | 💪 effort | 🧠 thinking | ...

A built-in update checker also pings GitHub on a configurable interval (off / daily / weekly / monthly) and shows a small 🔔 hint in the status line when a new release is available.

How it Works

• Claude Code passes a JSON object to the status line via stdin.
• The script reads it, determines the git branch via git branch --show-current in the current working directory, and returns the formatted, colored output
• Colors automatically shift green → yellow → red depending on usage.
• The label next to a bar uses the colour of the bar's most recent segment, so the active threshold stays visible at a glance.
• Implemented in Python 3 (standard library only) and works on Linux, macOS, and Windows.

Color Scheme

| Element | Color | |---------|-------| | Opus | 🟡 Gold | | Sonnet | 🔵 Light blue | | Haiku | ⚪ White | | thinking:on | 🟢 Teal | | thinking:off | ⚫ Dimmed gray | | effort / ctx / tkn / 5h / 7d (low) | 🟢 Green | | effort / ctx / tkn / 5h / 7d (medium) | 🟡 Yellow | | effort / ctx / tkn / 5h / 7d (high) | 🔴 Red | | dir / branch / worktree labels | 🟤 Rust brown | | dir / branch / worktree values | 🟠 Warm bronze |

Display modes

Each line 1 metric can be rendered in one of four modes (text / bar / both / off):

| Mode | Example (ctx at 42%) | |------|----------------------| | text | ctx: 42% | | bar | ctx ▰▰▰▰▱▱▱▱▱▱ | | both | ctx ▰▰▰▰▱▱▱▱▱▱ 42% | | off | (hidden) |

Defaults: effort, ctx, 5h, 7d use bar; model, thinking, tkn use text.

Decoration: emoji or label

A single global switch controls whether every segment (on both lines) is prefixed with an emoji or a word label:

| Segment | Emoji | Label | |---------|-------|-------| | model | 🤖 | model | | effort | 💪 | effort | | thinking | 🧠 | thinking | | ctx | 📦 | ctx | | tkn | 🎫 | tkn | | 5h | 🕔 | 5h | | 7d | 📆 | 7d | | dir | 📁 | dir | | branch | 🌿 | branch | | worktree | 🌳 | worktree |

Default: emoji.

Bar style

When a metric is shown as a bar (bar or both mode), the glyphs are configurable:

| Style | Filled | Empty | Look | |-------|--------|-------|------| | fill | ▰ | ▱ | Subtle, slightly rounded | | block | █ | ░ | Strong contrast, classic | | dot (default) | ● | ○ | Battery-indicator style | | square | ■ | □ | Clean, geometric |

Thresholds

Default thresholds (configurable in the TUI):

| Metric | Yellow at | Red at | |--------|-----------|--------| | ctx | 60% | 80% | | tkn | 60% | 80% | | 5h rate limit | 60% | 80% | | 7d rate limit | 60% | 80% |

Requirements

| Platform | Requirements | |----------|--------------| | Linux | git, Python 3.8+ | | macOS | git, Python 3.8+ | | Windows | git, Python 3.8+, plus windows-curses for the TUI |

None of the scripts install Python automatically — if it's missing they print a warning with a hint. Install Python yourself:

sudo apt install git python3        # Debian / Ubuntu / Mint
sudo dnf install git python3        # Fedora / RHEL / CentOS
sudo pacman -S git python            # Arch / Manjaro
sudo zypper install git python3     # openSUSE

Via Homebrew:

brew install git python

Alternatively, running git --version will prompt to install Git via the Xcode Command Line Tools. Python can also be installed from python.org.

Install Git from git-scm.com and Python from python.org (or via winget):

winget install --id Git.Git -e
winget install --id Python.Python.3.12 -e
pip install windows-curses

When installing Python, make sure "Add python.exe to PATH" is checked.

Installation

Everything — install, configure, uninstall — runs through a single interactive TUI. There is no separate install script: the TUI's main menu has a toggle entry that becomes Install when the status line is not registered in ~/.claude/settings.json and Uninstall when it is. Selecting it copies (or removes) statusline.py in ~/.claude/ and updates settings.json accordingly. Existing files are backed up as .bak.<timestamp>.

There are two ways to launch the TUI:

Option A — via npx (recommended)

Requires Node.js ≥ 14 (node --version to check). Install from nodejs.org if needed.

npx -y @luport-dev/claude-code-statusline

This fetches the npm wrapper, locates python3 (or python / py on Windows), and starts the TUI. From there pick Install from the main menu, configure as desired, then q to save and quit. Restart Claude Code afterwards.

The -y flag auto-confirms npx's download prompt so the call never blocks.

Option B — clone the repo

git clone https://github.com/luport-dev/claude-code-statusline.git
cd claude-code-statusline

Then run the platform-specific launcher:

./setup/linux/setup.sh    # Linux
./setup/mac/setup.sh      # macOS
setup\win\setup.cmd       # Windows (CMD)

All three are thin wrappers that just call python3 setup/settings.py (or python on Windows).

From there pick Install from the main menu, configure as desired, then q to save and quit. Restart Claude Code afterwards.

Manual installation

If you'd rather skip the TUI entirely, copy scripts/statusline.py to ~/.claude/statusline.py and add the following to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "python3 /home/YOUR_USERNAME/.claude/statusline.py"
  }
}

On Windows use forward slashes and python instead of python3:

{
  "statusLine": {
    "type": "command",
    "command": "python C:/Users/YOUR_USERNAME/.claude/statusline.py"
  }
}

Windows path note: Claude Code routes status line commands through Git Bash when available, and backslashes get eaten as escape characters. See the official docs.

Restart Claude Code — the status line is loaded on next startup.

Configuration TUI

The same TUI handles install/uninstall and all configuration. Settings are saved to ~/.claude/statusline_config.json.

Main menu

Metrics visibility — per-metric display mode

Thresholds

Git visibility

Decoration

Bar style

Update checks

• When a newer release is available on GitHub, a small 🔔 v0.1.1 available segment is appended to line 2 - also a banner appears in the TUI's main menu.
• The check runs in a background thread (3 s timeout) so the status line never blocks.
• Result is cached in ~/.claude/statusline_update.json. Default interval: weekly.

Files

| File | Description | |------|-------------| | scripts/statusline.py | Status line script (all platforms) | | setup/settings.py | Interactive TUI — handles install, configure, and uninstall | | setup/default_config.json | Default configuration (copied on first install) | | setup/linux/setup.sh | Linux launcher | | setup/mac/setup.sh | macOS launcher | | setup/win/setup.cmd | Windows launcher | | npm/ | npm wrapper that enables npx -y claude-code-statusline |

License

This project is licensed under the MIT License. See LICENSE for details.