lockstep
4 min readNaman Jain

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

FieldHolds
model.display_nameThe current model
workspace.current_dir, workspace.project_dirCurrent directory, and where the session started
cost.total_cost_usdEstimated session cost, computed locally at list price; may differ from your bill
cost.total_duration_msSession wall-clock time
cost.total_lines_added, cost.total_lines_removedLines changed
context_window.used_percentageHow full the context window is
rate_limits.five_hour.used_percentage, rate_limits.seven_day.used_percentageRate limit used, 0 to 100
effort.levelThe session's reasoning effort
session_id, session_nameSession 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 COLUMNS and LINES. Claude Code captures your script's output, so tput cols can'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

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