Claude Code Status Line — real-time context window usage with color-coded progress bar (model, tokens remaining, autocompact threshold)

statusline-README.md

Claude Code Context Window Status Line

A status line for Claude Code that displays real-time context window usage with a color-coded progress bar. Shows the current model, total window size, and how many tokens remain before autocompact triggers.

Example Output

[Claude 4.5 Sonnet · 200K] ####------ 92K/140K left

• Green ####------ — safe (< 70% used)
• Yellow #######--- — warning (70–89% used)
• Red #########- — critical (≥ 90% used)

Cross-Platform Compatibility

Works on macOS, Linux, and Windows (via Git Bash or WSL).

The script intentionally uses POSIX-portable constructs:

• printf instead of echo -e (which behaves differently across shells)
• jq for JSON parsing (available on all platforms)
• Standard awk and tr for text formatting
• No Bash-specific features beyond basic arithmetic

Prerequisites

• jq must be installed (brew install jq / apt install jq / choco install jq)

Setup

1. Save the script

Copy statusline.sh to ~/.claude/scripts/ and make it executable:

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

2. Configure settings.json

Add the following to your ~/.claude/settings.json (or project-level .claude/settings.json):

{
  // (optional) Set the autocompact threshold — default is 90%.
  // The progress bar and "left" counter are based on this percentage of the total window.
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "70"   // ← change to your preferred %
  },

  // Add this block to enable the status line
  "statusLine": {
    "type": "command",
    "command": "$HOME/.claude/scripts/statusline.sh"
  }
}

If your settings.json already has other keys, just merge the "env" and "statusLine" sections into the existing object.

How It Works

1. Claude Code pipes a JSON payload to the script's stdin on every turn
2. The script reads model, context_window_size, and current token usage from the JSON
3. It calculates usage against the effective limit (window × autocompact %)
4. Outputs a single formatted line with model info, a 10-char progress bar, and remaining tokens

statusline.sh

#!/bin/bash
# Status line script for Claude Code
# Displays: model name, total window, progress bar, tokens remaining until autocompact

input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
MAX_TOKENS=$(echo "$input" | jq -r '.context_window.context_window_size // 0')

# Use pre-calculated used_percentage from Claude Code (source of truth)
# This aligns with the native "Context left until auto-compact" indicator
USED_PCT_RAW=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
TOKENS=$((MAX_TOKENS * USED_PCT_RAW / 100))

# Effective limit based on autocompact threshold
AUTOCOMPACT_PCT="${CLAUDE_AUTOCOMPACT_PCT_OVERRIDE:-90}"
EFFECTIVE_LIMIT=$((MAX_TOKENS * AUTOCOMPACT_PCT / 100))

# Tokens remaining until autocompact triggers
REMAINING=$((EFFECTIVE_LIMIT - TOKENS))
[ "$REMAINING" -lt 0 ] && REMAINING=0

# Usage percentage relative to effective limit
if [ "$EFFECTIVE_LIMIT" -gt 0 ]; then
  USAGE_PCT=$((TOKENS * 100 / EFFECTIVE_LIMIT))
else
  USAGE_PCT=0
fi
[ "$USAGE_PCT" -gt 100 ] && USAGE_PCT=100

# Color thresholds: green (safe), yellow (warning), red (critical)
GREEN='\033[32m'
YELLOW='\033[33m'
RED='\033[31m'
RESET='\033[0m'

if [ "$USAGE_PCT" -ge 90 ]; then
  COLOR="$RED"
elif [ "$USAGE_PCT" -ge 70 ]; then
  COLOR="$YELLOW"
else
  COLOR="$GREEN"
fi

# Progress bar (10 chars wide)
FILLED=$((USAGE_PCT / 10))
EMPTY=$((10 - FILLED))
BAR=""
[ "$FILLED" -gt 0 ] && BAR=$(printf "%${FILLED}s" | tr ' ' '#')
[ "$EMPTY" -gt 0 ] && BAR="${BAR}$(printf "%${EMPTY}s" | tr ' ' '-')"

# Format token counts as K (thousands)
MAX_K=$(echo "$MAX_TOKENS" | awk '{printf "%.0fK", $1/1000}')
EFFECTIVE_K=$(echo "$EFFECTIVE_LIMIT" | awk '{printf "%.0fK", $1/1000}')
REMAINING_K=$(echo "$REMAINING" | awk '{printf "%.0fK", $1/1000}')

# Build output (printf is POSIX-portable, echo -e is not)
printf '[%s · %s] %b%s%b %s/%s left\n' "$MODEL" "$MAX_K" "$COLOR" "$BAR" "$RESET" "$REMAINING_K" "$EFFECTIVE_K"

Fix: token count now uses pre-calculated used_percentage from Claude Code instead of manual calculation (input + cache tokens). This aligns the status line with the native auto-compaction indicator.