Claude Code statusline: Setup and Examples

The status line is a customisable bar at the bottom of Claude Code. It runs a command you configure, passes it live session data as JSON on stdin, and shows whatever the command prints. The most useful thing to put there is how full your context window is — the number that most affects how well Claude works. (What is a context window?)

The quick way: /statusline

/statusline show the model, context percentage and git branch

Claude writes the script and the settings for you. Run /statusline with no description and it builds one from your shell prompt.

Configuring it by hand

In ~/.claude/settings.json:

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

A one-liner with jq works too:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

padding adds horizontal spacing; refreshInterval (seconds, minimum 1) re-runs the command on a timer for time-based data, in addition to the normal updates after each message and tool call.

The data you get

Some of the most useful fields:

Field	Meaning
`model.display_name`	Current model
`workspace.current_dir`, `workspace.project_dir`	Where you are / where you started
`workspace.git_worktree`	Worktree name, if in one
`context_window.used_percentage`	How full the context is
`context_window.context_window_size`	200K, or 1M with extended context
`cost.total_cost_usd`	Estimated session cost at list price (not your bill)
`cost.total_lines_added` / `_removed`	Lines changed
`rate_limits.five_hour.used_percentage`	Subscription 5-hour window usage
`rate_limits.seven_day.used_percentage`	Weekly usage

cost.total_cost_usd is estimated client-side; on a subscription, the rate_limits fields are the more meaningful numbers. (Claude Code usage limits)

A complete example

~/.claude/statusline.sh:

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

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(basename "$(echo "$input" | jq -r '.workspace.current_dir')")
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty' | cut -d. -f1)

BRANCH=$(git -C "$(echo "$input" | jq -r '.workspace.current_dir')" branch --show-current 2>/dev/null)

# colour the context figure: green < 50, yellow < 80, red after
if   [ "$PCT" -lt 50 ]; then C="\033[32m"
elif [ "$PCT" -lt 80 ]; then C="\033[33m"
else C="\033[31m"; fi

LINE="[$MODEL] $DIR"
[ -n "$BRANCH" ] && LINE="$LINE  $BRANCH"
LINE="$LINE  ${C}ctx ${PCT}%\033[0m"
[ -n "$WEEK" ] && LINE="$LINE  week ${WEEK}%"

echo -e "$LINE"

chmod +x ~/.claude/statusline.sh

Multiple echo lines produce a multi-line status line. (Bash scripting for beginners)

Using it well

Act on the context number. Around 60–70%, consider /compact with instructions or finishing the task and /clear. (/compact vs /clear)
Watch the weekly limit if you're on Pro or Max, and switch heavy routine work to a cheaper model when it climbs. (How to change the model)
Show the worktree when running parallel sessions, so you always know which one you're in. (Parallel agents with worktrees)

Performance and safety

Keep the script fast — it runs often. Avoid network calls; cache anything slow to a temp file with a timestamp.
The status line command runs outside the sandbox with your full permissions, like hooks. Don't point it at scripts you haven't read. (Claude Code sandbox)
On Windows, use a PowerShell script or run Claude Code in WSL.

To turn it off, remove the statusLine key (or run /statusline and ask it to remove it).

EasySpawn runs Claude Code on a persistent server, so your status line, settings and scripts are the same whether you connect from your laptop, a browser or your phone. See how it works or join the waitlist.

Claude Code Status Line: Show Context, Cost and Git Branch