Custom Claude Code status line with truecolor gradient context bar, version alerts, and model info

gist-readme.md

Claude Code Custom Status Line

A rich, colorful status line for Claude Code that shows context usage, model info, version update alerts, and more — right in your terminal.

What it shows

Section	Example	Description
Version	1.0.30	Current version with icon; turns red with →1.0.31 suffix when outdated
Model	Claude 4.6 Opus	Active model display name
Context bar	⣿⣿⣿⣿⣀⣀⣀⣀	Braille progress bar with amber→orange→rust truecolor gradient
Usage	42% 84K/200K	Context window percentage and token counts
Working dir	~/Projects/myapp	Shortened cwd (home → ~)
Session	a1b2c3d4	First 8 chars of session ID

Features

• Truecolor gradient progress bar using braille characters (⣿ filled, ⣀ empty)
• Version update check — polls npm registry every 30 min (cached in /tmp)
• Compact token display — shows 84K/200K instead of raw numbers
• Zero dependencies beyond bash and jq

Setup

1. Save statusline.sh to ~/.claude/statusline.sh and make it executable:

   chmod +x ~/.claude/statusline.sh

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

   {
     "statusLine": {
       "type": "command",
       "command": "bash -c '$HOME/.claude/statusline.sh'"
     }
   }

3. Restart Claude Code — the status line appears at the bottom of the TUI.

How it works

Claude Code pipes a JSON blob to the status line command via stdin on every render. The script reads it with jq to extract:

• context_window.context_window_size — max context tokens
• context_window.current_usage — input, cache creation, and cache read tokens
• model.display_name / model.id — active model
• version — current CLI version
• cwd — working directory
• session_id — current session

The gradient is computed in pure bash arithmetic — no external color libraries needed.

Customization

• Bar width: Change bar_width=8 to make the progress bar wider/narrower
• Colors: Edit the r1,g1,b1 / r2,g2,b2 / r3,g3,b3 RGB values for a different gradient
• Cache duration: Adjust cache_max_age=1800 (seconds) for version check frequency

statusline-preview.svg

statusline.sh

#!/bin/bash

input=$(cat)

# Extract data
context_limit=$(echo "$input" | jq -r '.context_window.context_window_size // 200000')
session_id=$(echo "$input" | jq -r '.session_id // "unknown"')
cwd=$(echo "$input" | jq -r '.cwd // ""')
model_name=$(echo "$input" | jq -r '.model.display_name // .model.id // "unknown"')
version=$(echo "$input" | jq -r '.version // "?"')

# Use current_usage (current context)
usage=$(echo "$input" | jq '.context_window.current_usage')
if [ "$usage" != "null" ] && [ "$usage" != "" ]; then
    total_used=$(echo "$usage" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')
    used_pct=$((total_used * 100 / context_limit))
else
    total_used=0
    used_pct=0
fi

# Colors
R="\033[0m"
B="\033[1m"
D="\033[2m"
c() { printf "\033[38;5;%sm" "$1"; }

format_k() {
    local n=$1
    if [ $n -ge 1000 ]; then
        echo "$((n/1000))K"
    else
        echo "$n"
    fi
}

used_fmt=$(format_k $total_used)
limit_fmt=$(format_k $context_limit)

# Check latest version (cached, refresh every 30 min)
cache_file="/tmp/.claude-latest-version"
cache_max_age=1800
latest=""
now=$(date +%s)

if [ -f "$cache_file" ]; then
    cache_age=$(( now - $(stat -c %Y "$cache_file" 2>/dev/null || echo 0) ))
    if [ $cache_age -lt $cache_max_age ]; then
        latest=$(cat "$cache_file")
    fi
fi

if [ -z "$latest" ]; then
    latest=$(npm view @anthropic-ai/claude-code version 2>/dev/null)
    if [ -n "$latest" ]; then
        echo "$latest" > "$cache_file"
    fi
fi

# Version indicator
if [ -n "$latest" ] && [ "$latest" != "$version" ]; then
    ver_color="\033[38;2;255;100;80m"
    ver_icon=" "
    ver_suffix=" ${D}→${latest}${R}"
else
    ver_color="\033[38;2;180;160;255m"
    ver_icon=" "
    ver_suffix=""
fi

# Braille progress bar - truecolor gradient O: Amber -> Orange -> Rust
bar_width=8
filled=$(( (used_pct * bar_width + 50) / 100 ))
# Gradient: (255,200,80) -> (230,130,30) -> (180,60,20)
r1=255; g1=200; b1=80
r2=230; g2=130; b2=30
r3=180; g3=60;  b3=20
er=60;  eg=60;  eb=60

bar=""
for ((i=0; i<bar_width; i++)); do
    if [ $i -lt $filled ]; then
        if [ $filled -gt 1 ]; then
            t=$((i * 200 / (filled - 1)))
        else
            t=0
        fi
        if [ $t -le 100 ]; then
            r=$(( r1 + (r2 - r1) * t / 100 ))
            g=$(( g1 + (g2 - g1) * t / 100 ))
            b=$(( b1 + (b2 - b1) * t / 100 ))
        else
            t2=$((t - 100))
            r=$(( r2 + (r3 - r2) * t2 / 100 ))
            g=$(( g2 + (g3 - g2) * t2 / 100 ))
            b=$(( b2 + (b3 - b2) * t2 / 100 ))
        fi
        bar+="\033[38;2;${r};${g};${b}m⣿${R}"
    else
        bar+="\033[38;2;${er};${eg};${eb}m⣀${R}"
    fi
done

# Shorten cwd (replace home with ~)
short_cwd=$(echo "$cwd" | sed "s|^$HOME|~|")

# Shorten session_id to first 8 chars
short_id="${session_id:0:8}"

# Build status line
printf '%b' "${B}${ver_color}${ver_icon}${version}${R}${ver_suffix}  "
printf '%b' "$(c 156) ${model_name}${R}  "
printf '%b' "${bar} "
printf '%b' "${B}${used_pct}%${R} ${used_fmt}/${limit_fmt}  "
printf '%b' "$(c 75) ${short_cwd}${R}  "
printf '%b\n' "$(c 243) ${short_id}${R}"