Claude Code status line: 5 examples and setup
Set up a custom Claude Code status line: /statusline, the settings field, the JSON your script receives, and five scripts for context, git, cost, and limits.
Most people find out their context window is nearly full when Claude Code compacts. A status line puts that, and anything else you care about, in a bar at the bottom of the terminal the whole time.
This guide covers setup and five scripts, based on Anthropic's status line documentation, checked on 16 November 2026.
How it works
The status line runs a command you configure. Claude Code sends session data to it as JSON on stdin and shows whatever it prints. It runs locally and uses no API tokens.
It updates when a session starts or resumes, when a new assistant message arrives, after /compact, when the permission mode changes, and on a timer if you set refreshInterval. Updates are debounced by 300ms.
Setup
The quick way. Describe what you want:
/statusline show model name and context percentage with a progress bar
Claude Code writes a script in ~/.claude/ and updates your settings.
By hand. Add a statusLine field to ~/.claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2
}
}
Optional fields: padding for spacing, refreshInterval in seconds for clocks or anything that changes while the session is idle, and hideVimModeIndicator if your script shows the vim mode itself. Make the script executable with chmod +x.
To remove it, run /statusline remove it or delete the field.
Fields you can use
| Field | Holds |
|---|---|
model.display_name | The current model |
workspace.current_dir, workspace.project_dir | Current directory, and where the session started |
cost.total_cost_usd | Estimated session cost, computed locally at list price; may differ from your bill |
cost.total_duration_ms | Session wall-clock time |
cost.total_lines_added, cost.total_lines_removed | Lines changed |
context_window.used_percentage | How full the context window is |
rate_limits.five_hour.used_percentage, rate_limits.seven_day.used_percentage | Rate limit used, 0 to 100 |
effort.level | The session's reasoning effort |
session_id, session_name | Session identity |
Some fields are missing until the first API response, so always give a fallback.
Example 1: one line, no script
An inline jq command in settings:
{
"statusLine": {
"type": "command",
"command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
}
}
Example 2: a context bar
~/.claude/statusline.py:
#!/usr/bin/env python3
import json, sys
d = json.load(sys.stdin)
pct = int((d.get("context_window") or {}).get("used_percentage") or 0)
bar = "#" * (pct // 10) + "-" * (10 - pct // 10)
print(f"{d['model']['display_name']} [{bar}] {pct}%")
Example 3: git branch and uncommitted changes
#!/bin/bash
input=$(cat)
dir=$(echo "$input" | jq -r '.workspace.current_dir')
model=$(echo "$input" | jq -r '.model.display_name')
branch=$(git -C "$dir" branch --show-current 2>/dev/null)
if [ -n "$branch" ]; then
changes=$(git -C "$dir" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
echo "$model | $branch ($changes changed)"
else
echo "$model | $(basename "$dir")"
fi
Running git on every update is cheap for small repositories. For large ones, the documentation has a pattern for caching expensive operations.
Example 4: cost and time
#!/bin/bash
input=$(cat)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
ms=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
mins=$((ms / 60000))
printf '$%.2f this session | %dm\n' "$cost" "$mins"
The cost is an estimate calculated on your machine, and it resets to zero when /clear starts a new session.
Example 5: two lines with rate limits
Each line your script prints becomes a row:
#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
ctx=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
echo "$model | context ${ctx}%"
[ -n "$five" ] && echo "limits: 5h ${five%.*}% | 7d ${week%.*}%"
You can also color output with ANSI escape codes, and make text clickable with OSC 8 links in terminals that support them, such as iTerm2, Kitty, and WezTerm.
Tips
- Read the terminal size from
COLUMNSandLINES. Claude Code captures your script's output, sotput colscan't see the terminal. - Keep scripts fast. A slow update is cancelled when a newer one starts.
- Status lines hide during the help menu and permission prompts.
- On Windows, use PowerShell or Git Bash; the documentation has examples.
Where Lockstep fits
Lockstep's CLI includes its own status line command, lockstep statusline, which shows unread items for the current repository: new decisions, changes, questions, and tasks from teammates, cached for 30 seconds so it stays fast. Lockstep itself keeps the team's approved decisions, captured from PRDs, Slack, and pull requests, and briefs Claude Code on the ones that apply at the start of each session.
See how it works.
Sources checked 16 November 2026
Related reading
For other settings, see Claude Code settings.json. For keeping context and cost down, see Claude Code best practices. For changing how Claude responds, see Claude Code output styles. For cutting usage, see how to reduce Claude Code token usage.
Frequently asked questions
- How do I set up a Claude Code status line?
- Run /statusline with a description, such as /statusline show model name and context percentage with a progress bar, and Claude Code writes a script in ~/.claude/ and updates your settings. Or add a statusLine field with type command and a command to your settings.json yourself.
- What data does the status line script receive?
- JSON on stdin, including model.display_name, workspace.current_dir, cost.total_cost_usd, cost.total_duration_ms, context_window.used_percentage, rate_limits for the 5-hour and 7-day windows, session_id, and more. Your script prints what to display.
- Does the Claude Code status line use tokens?
- No. It runs locally and doesn't consume API tokens. It updates when a new assistant message arrives, after /compact, when the permission mode changes, and on a timer if you set refreshInterval.
- How do I remove the status line?
- Run /statusline and ask it to remove or clear the status line, or delete the statusLine field from your settings.json.
- Why does my status line show empty values?
- Some fields are absent until the first API response, or outside a git repository. Use fallbacks in your script, such as jq's // 0, so missing fields print a default instead of null.
Keep reading