Claude Code Status Line

A sober status bar for Claude Code that displays real-time usage metrics using server-side rate limit data.

Features

Feature	Description
Current Model	Active Claude model (Opus, Sonnet, Haiku)
Project Folder	Current working directory name
Git Branch	Current branch (⎇), hidden outside a repo
Session Tokens	Input (↓), Output (↑), and Total (Σ) for current session
5hr Window	Progress bar + percentage + time to reset (relative and absolute)
Weekly Quota	Percentage + time to reset (relative and absolute)
Context Window	Context usage percentage
Effort Level	Thinking effort (L/M/H/⚡)
Responsive Layout	When the line is wider than the terminal, segments stack onto multiple lines
Configurable Model Color	Set the model name's color (256-color index)
Cold Start Metrics	Shows last-known metrics when Claude Code starts before receiving new data

Screenshot

[Opus] 📁 claude-statusline ⎇ main │ ↓0·↑0·Σ0 │ 5h:▓▓░░░░░░  30% (3h29m→04:33) │ wk:43% (4d3h→05:00) │ ctx:15% │ H

Architecture

Claude Code (stdin JSON with rate_limits) → statusline.sh → statusline_display.sh → [ANSI status bar]

Rate limit percentages (five_hour, seven_day) come directly from Claude Code's stdin JSON — authoritative server-side data, no estimation or local calculation needed.

Installation

Prerequisites

• jq — JSON processor

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Fedora/RHEL
sudo dnf install jq

Quick Install

git clone <repo-url> && cd claude-statusline
./setup.sh

The installer defaults to ~/.claude, writes a native refresh interval of 5 seconds, and prints any post-install notes.

Options:

Flag	Default	Description
--config-dir <path>	~/.claude	Claude config directory to install into. Honored by --uninstall too.
--refresh-interval <secs>	5	Re-run the status line every N seconds for live updates. Use 0 or none for event-driven updates only.
--no-stack	(stack)	Don't wrap segments onto multiple lines when the window is too narrow — keep a single line that may overflow.
--model-color <0-255>	80	256-color index for the model name (default cyan).

# Install into a custom config directory with a 10s refresh
./setup.sh --config-dir ~/.config/claude --refresh-interval 10

Manual Install

1. Copy scripts (swap ~/.claude for your config dir if different):

   mkdir -p ~/.claude/statusline
   cp statusline.sh statusline_display.sh ~/.claude/statusline/
   chmod +x ~/.claude/statusline/*.sh

2. Edit ~/.claude/settings.json:

   {
     "statusLine": {
       "type": "command",
       "command": "~/.claude/statusline/statusline.sh",
       "refreshInterval": 5
     }
   }

3. Restart Claude Code

How It Works

Project Folder

Displays the current working directory name, sourced from cwd in Claude Code's stdin JSON.

Git Branch

Shows the current branch (prefixed with ⎇) next to the folder name, detected with a single git rev-parse against the working directory. This handles subdirectories and worktrees; on a detached HEAD it shows the short commit SHA instead. Outside a git repository (or if git is unavailable) the segment is simply hidden. The branch name is shown in full; on a narrow window the whole line stacks onto multiple rows rather than truncating — see Responsive Layout.

Session Tokens

Comes from context_window.total_input_tokens and total_output_tokens in Claude Code's stdin JSON. Real-time and accurate.

5-Hour Window & Weekly Quota

Read from rate_limits.five_hour and rate_limits.seven_day in Claude Code's stdin JSON. These are server-side percentages that match exactly what the Claude web UI shows. Available after the first API response in a session.

Context Window

Read from context_window.used_percentage — how much of the model's context window is in use.

Effort Level

Read from effort_level in stdin JSON. Falls back to "medium" if not available.

Responsive Layout

The status line reads the terminal width from the COLUMNS environment variable that Claude Code exports to statusLine commands (Claude Code v2.1.153+; on older versions COLUMNS is unset and everything renders on a single line). When the assembled line is wider than the window, the │-separated segments are wrapped onto multiple lines — greedily packing as many segments per line as fit. Each segment renders at full fidelity (the branch is never truncated, the 5h bar is never hidden); only the wrapping responds to width.

Env var	Default	Effect
CLAUDE_STATUSLINE_STACK	1	Set 0 to never wrap onto multiple lines (single line that may overflow).
CLAUDE_STATUSLINE_MODEL_COLOR	80	256-color index for the model name (e.g. 203 for salmon, 114 for green).

Cold Start Metrics

When Claude Code starts a new session, the status line automatically caches the last received rate limits and effort level to .last_metrics.json alongside the installed scripts (e.g. ~/.claude/statusline/.last_metrics.json, or inside your --config-dir). When Claude Code hasn't received new data yet (before the first API response), the display merges the cached values into the output, so you see the previous session's metrics instead of 0%/(inactive). Once the first API response arrives with current rate limit data, that takes precedence and the cache is updated.

Live Refresh

By default Claude Code only re-runs the status line on events (new assistant messages, /compact, permission changes, etc.). During long idle/tool runs the time-based fields (5h/wk countdowns) would otherwise go stale. The installer sets refreshInterval (in seconds, default 5) in the statusLine config, which Claude Code re-runs on a timer in addition to event updates. This is the official native mechanism — there is no persistOnToolUse setting. Set --refresh-interval 0 (or none) at install time to keep updates event-driven only.

Customization

Colors

Edit statusline_display.sh to change the color palette:

FG_CYAN='\033[38;5;80m'
FG_BLUE='\033[38;5;75m'
FG_GREEN='\033[38;5;114m'
FG_YELLOW='\033[38;5;222m'
FG_ORANGE='\033[38;5;216m'
FG_RED='\033[38;5;174m'

The model name color can be changed without editing the file — set CLAUDE_STATUSLINE_MODEL_COLOR to a 256-color index (install with setup.sh --model-color <0-255>, default 80).

Progress Bar

# Width (default 8 characters)
render_progress_bar "$window_pct" 8

# Color thresholds: green <50%, yellow 50-75%, orange 75-90%, red >90%

Troubleshooting

Status line not showing

1. Accept workspace trust dialog when Claude Code prompts
2. Check permissions: chmod +x ~/.claude/statusline/*.sh
3. Test: echo '{}' | ~/.claude/statusline/statusline.sh
4. Confirm jq is installed: command -v jq

0% / (inactive) for rate limits

Before the first API response in a session, the display shows cached metrics from the last session. After Claude Code receives its first response, current rate limits appear. If you want to clear the cache, delete ~/.claude/statusline/.last_metrics.json.

Percentages differ slightly from web UI

Both should match exactly since they use the same server-side data. Small timing differences are possible since the status line reads the data at a slightly different moment.

Uninstallation

./setup.sh --uninstall

If you installed into a custom config directory, pass the same flag so uninstall targets it:

./setup.sh --uninstall --config-dir ~/.config/claude

Or manually:

rm -rf ~/.claude/statusline
# Remove statusLine from ~/.claude/settings.json

Files

File	Purpose
statusline.sh	Entry point, pipes stdin to display script
statusline_display.sh	Renders ANSI-colored status bar
setup.sh	Installation/uninstallation script

License

MIT License — feel free to modify and share.

Credits

Inspired by the Claude Code community tools:

• ccusage
• ccstatusline
• claude-code-log