/statusline - See Context Usage at a Glance in Claude Code

What is it

Claude Code can show a persistent status bar at the very bottom of your terminal. It displays whatever you want: model name, how much of your context window you've used, session cost, git branch, token counts. It updates after every response.

The status bar is powered by a shell script that receives session data as JSON and prints whatever you want displayed. You don't need to write the script yourself. The /statusline command generates one for you from a plain English description.

Statusline documentation

What problems it solves

You're deep into a refactor and Claude starts giving shorter, less detailed responses. Something feels off but you can't tell why. Turns out your context window hit 85% and Claude is running out of room. Without the status bar, you'd have no way to know until things got noticeably worse. With it, you see the percentage tick up in real time and know to run /compact before it becomes a problem.

Or you're running multiple Claude sessions in different terminals. You switch between them and forget which one is on Opus and which is on Sonnet. The status bar shows the model name on every session so you always know what you're working with.

Or you're on a Max plan and want to keep an eye on your rate limits. The status bar can show your 5-hour and 7-day usage percentages so you know when to pace yourself.

How to use it

How I set mine up

I didn't know the statusline existed. I saw someone's screenshot with context stats at the bottom of their terminal and asked Claude Code: "How do I get that usage bar to show up in my sessions?"

Claude figured out it was the statusline feature, explained what it does, and asked if I wanted it set up. I said yes. It generated a shell script, saved it to ~/.claude/, updated my settings, and the bar appeared on my next interaction. The whole thing took about 30 seconds.

Then Claude asked if I also wanted account-level rate limits (5-hour and 7-day usage). I said yes to that too, and it updated the script.

Want your bar to look like mine?

Here's what I ended up with:

Opus 4.6 (1M context) | [████████░░░░░░░░░░░░░░░░░░░░░░] | 26% | 260k / 1000k | $20.32 | 5h: 8% 7d: 32%

Model name, context window size, progress bar, percentage, used vs total tokens, session cost, and account-level rate limits. All updating after every response.

The context stats (progress bar, percentage, token count) are per-session. Each Claude Code session has its own context window, so these numbers reflect how full that specific conversation is. The rate limits (5h and 7d) are account-level and shared across all sessions.

Option 1: Ask Claude to build it for you. Paste this into Claude Code:

Set up a statusline showing: model name,
30-char progress bar, context %, used/total
tokens in k, session cost, and 5h/7d rate
limits. Derive used tokens from percentage
times context window size.

Claude will generate the script and configure everything. Done in 30 seconds.

Option 2: Use the exact script I run. Save this to ~/.claude/statusline.sh:

#!/usr/bin/env bash
input=$(cat)

model_name=$(echo "$input" | jq -r '.model.display_name // "Unknown"')
context_size=$(echo "$input" | jq -r '.context_window.context_window_size // 0')
used_pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
input_tokens=$(echo "$input" | jq -r '
((.context_window.used_percentage // 0) / 100
 * (.context_window.context_window_size // 0))
| floor')

if [ "$context_size" -ge 1000000 ] 2>/dev/null; then
ctx_label="$(echo "$context_size" | awk '{printf "%gM", $1/1000000}') context"
elif [ "$context_size" -ge 1000 ] 2>/dev/null; then
ctx_label="$(echo "$context_size" | awk '{printf "%gk", $1/1000}') context"
else
ctx_label="$context_size context"
fi

bar_width=30
[ -z "$used_pct" ] || [ "$used_pct" = "null" ] && used_pct=0
filled=$(echo "$used_pct $bar_width" | awk '{n=int($1/100*$2+0.5); if(n>$2) n=$2; if(n<0) n=0; print n}')
empty=$((bar_width - filled))
bar=""
for i in $(seq 1 $filled); do bar="$bar█"; done
for i in $(seq 1 $empty); do bar="$bar░"; done

used_k=$(echo "$input_tokens" | awk '{printf "%dk", $1/1000}')
total_k=$(echo "$context_size" | awk '{printf "%dk", $1/1000}')
pct_display=$(echo "$used_pct" | awk '{printf "%.0f%%", $1}')

cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
cost_fmt=$(printf '$%.2f' "$cost")

five_h=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
seven_d=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
rate_info=""
[ -n "$five_h" ] && rate_info=" | 5h: $(printf '%.0f' "$five_h")%"
[ -n "$seven_d" ] && rate_info="$rate_info 7d: $(printf '%.0f' "$seven_d")%"

printf "%s | [%s] | %s | %s / %s | %s%s" "$model_name" "$bar" "$pct_display" "$used_k" "$total_k" "$cost_fmt" "$rate_info"

chmod +x ~/.claude/statusline.sh

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

Available data

Your script gets a JSON object with fields like:

• model.display_name: current model name (Opus, Sonnet, etc.)
• context_window.used_percentage: how full the context window is
• context_window.context_window_size: max tokens (200k or 1M)
• context_window.current_usage.input_tokens: tokens used in current context
• cost.total_cost_usd: session cost in dollars
• cost.total_duration_ms: how long the session has been running
• rate_limits.five_hour.used_percentage: rate limit usage (Claude.ai subscribers)

Pro tips

The /statusline command is the way to go for most people. Describe what you want and it generates the script. If you want to tweak it later, the script lives at ~/.claude/statusline-command.sh (or whatever the command named it) and you can edit it directly.

You can output multiple lines. Each echo in your script creates a separate row. I've seen people put git branch info on line one and the context bar on line two.

The status bar runs locally and doesn't use any API tokens. It updates after each assistant message, when you change permission modes, or when you toggle vim mode.

References

• Statusline documentation
• Claude Code settings reference
• Related tips: /compact - Free Up Memory Mid-Session · Shift+Tab - Cycle Permission Modes