Claude Code statusline: set it up, show your limits, keep the history

The Claude Code statusline is a row at the bottom of the terminal that runs a script you pick and shows whatever that script prints: model, context use, session cost, git branch, and on a Pro, Max or Ultra plan your five-hour and weekly limits. Set it up with the /statusline command or a statusLine entry in your settings, or let ccstatusline build it for you, then add UsageAtlas if you also want those limits with history and alerts after the terminal closes.

This guide follows Anthropic's status line documentation as of November 2026.

How the status line works #

Claude Code sends your script a block of JSON on standard input and displays what comes back on standard output. The script runs on your machine and costs no API tokens. It fires when a session starts, after each new assistant message, after /compact, when the permission mode changes, and when a limit window reaches its reset time. Updates are batched over 300 milliseconds, so a burst of changes runs the script once.

Output can span several lines, use ANSI colors, and include clickable links in terminals that support them. Keep it short. The row shares space with system notifications, and narrow windows cut it off.

Set it up in one command #

The quickest route is to describe what you want:

/statusline show model, context percentage and my weekly limit

Claude Code writes a script into ~/.claude/ and points your settings at it. Run /statusline with no description to copy the look of your shell prompt, and /statusline delete to remove it.

Or configure it by hand #

Add this to ~/.claude/settings.json, or to a project's settings file:

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

A minimal Bash script for macOS or Linux, using jq:

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
CTX=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
echo "$MODEL | ctx ${CTX}% ${WEEK:+| week ${WEEK}%}"

Make it executable with chmod +x. On Windows, Claude Code runs the command through Git Bash when it is installed and PowerShell otherwise; write the path with forward slashes, because Git Bash swallows backslashes and the row stays blank.

What your script can read #

Two catches on the limit fields. They appear only for claude.ai Pro, Max and Ultra subscribers, or behind a gateway with a spend limit, and only after the first API response of the session. Write scripts that print nothing when they are missing. The cost field is an estimate and can differ from your bill.

Skip the script with ccstatusline #

If you would rather choose widgets than write Bash, ccstatusline is one of two community projects Anthropic's docs name. Run npx -y ccstatusline@latest, pick widgets in its terminal menu, and it writes the statusLine entry for you. It covers the five-hour block, weekly usage, reset timers, cost, context and git, with Powerline themes. It is free and MIT licensed.

Where the status line stops #

A status line lives inside one Claude Code window. Close the terminal and the numbers go with it. It shows nothing about Codex or Cursor, and Claude Code deletes local session files after 30 days by default, so last month's pattern is gone too.

That is the gap UsageAtlas fills. It is a free, open-source desktop app for Windows, macOS and Linux that keeps your Claude Code five-hour and weekly windows, reset times, tokens and estimated cost in one place, with daily history and a desktop alert when a window runs low. It reads the credentials and local logs already on your machine, needs no account for local tracking, and never reads prompts or responses. Its comparison of ccstatusline and a usage dashboard explains why many people run both: they work side by side without conflicting.

If you only use Claude Code and look at the limit while typing, a status line alone is enough.