Customize the Claude Code status line

The status line is a bar at the bottom of Claude Code that runs a shell script you choose. Claude Code sends the script some JSON about your session, and whatever the script prints is what you see. It is a quick way to keep the model, the context usage or the git branch in view while you work.

Per the documentation, it runs locally and does not use API tokens.

The easy way: ask for it

Describe what you want and Claude Code writes the script and updates your settings:

/statusline show model name and context percentage with a progress bar

It saves a script under ~/.claude/ and may ask you to approve the file edits. To remove it later, run /statusline and ask it to delete the status line, or delete the statusLine field from your settings yourself.

The manual way

Add a statusLine entry to your user settings (~/.claude/settings.json) or to a project's settings. Set type to "command" and point command at a script:

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

Optional fields: padding adds horizontal spacing, refreshInterval re-runs the command every N seconds (the minimum is 1; useful for a clock), and hideVimModeIndicator hides the built-in vim mode text if your script prints the mode itself. For where this file lives and which settings file wins, see the settings guide.

A minimal script, using jq to read the JSON (you may need to install it):

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
echo "$model | ${pct}% context"

Save it as ~/.claude/statusline.sh and run chmod +x ~/.claude/statusline.sh. Claude Code reloads settings automatically, so the bar appears as soon as you save.

Test it before you rely on it

Feed the script fake data from your terminal:

echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25}}' | ~/.claude/statusline.sh

If that prints one clean line, the script is fine.

What data it gets

The model name and the current directory.
Context window usage as a percentage. It is worked out from input tokens only, taken from the last API response. /context adds an estimate for what came after, so it can read a little higher. See the context window guide.
Session cost and duration, and lines added and removed. The cost is an estimate worked out on your machine at list price, and the documentation says it may differ from your actual bill.
Your session ID and name, and the git worktree name if you are in one.
Subscription rate limits (the 5-hour and 7-day windows), only for claude.ai Pro and Max subscribers (or behind an organization gateway with spend limits), and only after the first response.

Some fields are empty before the first API response, so give your script a fallback such as // 0.

When it updates

The script runs when a session starts or resumes, when a new assistant message arrives, when /compact finishes, and when the permission mode or vim mode changes. Updates are batched with a 300 ms delay, and if one is still running when another starts, the older run is cancelled. A slow script therefore holds up the display, so keep it fast. Cache slow commands such as git status, and name the cache file after the session ID rather than a process ID, which changes on every run.

Colors, several lines and links

Each line you print becomes a row. ANSI color codes work if your terminal supports them, and OSC 8 escape sequences make clickable links in terminals that support them (the documentation names iTerm2, Kitty and WezTerm, and says Terminal.app does not). Complex escape sequences can occasionally garble the display, so if you see corrupted text, try plain output. Your script cannot ask the terminal for its width, but Claude Code sets the COLUMNS and LINES environment variables before it runs.

On Windows

Claude Code runs the command through Git Bash if it is installed, or PowerShell if not. Git Bash eats unquoted backslashes, so write paths with forward slashes. To use a PowerShell script:

{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
  }
}

If the bar stays blank

The folder is not trusted yet. The status line stays blank until you accept the workspace trust dialog, because it runs a shell command.
The script exits with an error or prints nothing. Output is shown only after the script exits with code 0.
It prints to stderr instead of stdout.
The script is not executable (chmod +x).
A managed setting from your organization can turn custom status lines off. Ask whoever manages it.
A disableAllHooks setting turns custom status lines off too (see the hooks guide for hooks in general).
Run claude --debug to see the script's errors.

Good to know

With a custom status line on, Claude Code stops showing most of its footer keyboard hints, such as the interrupt reminder.
The bar hides briefly during some screens, such as the help menu and permission prompts.
If you want to track usage rather than just look at it, the quota guide covers ways to use less.

Try it on something harmless

Run /statusline show model name and context percentage.
Send one message and watch the number change.
If you do not like it, run /statusline delete.

This follows Anthropic's status line documentation as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case. Fields and behavior can change between versions, and where this page and the documentation disagree, the documentation wins.

The free loop-stop skill gives long tasks a limit and a stop rule. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.