Guides

Claude Code status line: show context, cost and usage limits

The status line is a row at the bottom of Claude Code that runs a script of yours: Claude Code sends the script the session’s data as JSON and shows whatever it prints. The quickest way to get one is to type /statusline followed by what you want to see, and Claude Code writes the script for you. It isn’t decoration: it’s the one place that can show, all the time, the model, how full the context is, the session’s cost, your git branch, and on Pro and Max your 5-hour and weekly usage limits. It runs on your machine and uses no tokens.

By Dmitry Mishunin, who builds Meowdoro · October 30, 2026 · checked against the Claude Code documentation that day

• The one-line setup
• Set it up by hand
• What your script receives
• A script for context and limits
• When it updates
• Ready-made status lines
• VS Code, Claude Desktop and SSH
• When it stays blank
• Questions

The one-line setup

Describe what you want after the command, and Claude Code writes a script into ~/.claude/ and adds it to your settings:

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

Run /statusline with nothing after it to copy your shell prompt instead. To remove the status line, run /statusline and ask it to clear it, or delete the statusLine entry from your settings.

Set it up by hand

Add a statusLine object to your user settings, or to a project’s settings for that project only:

~/.claude/settings.json

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

• command is a script path or an inline shell command. It runs in a shell, so a one-liner such as jq -r '"[\(.model.display_name)] \(.context_window.used_percentage // 0)% context"' works too.
• padding adds spaces around the text; the default is 0.
• refreshInterval (version 2.1.97 and later) also re-runs the command every N seconds, at least 1. Use it for a clock, or for anything that changes while the session is idle.
• hideVimModeIndicator hides the built-in -- INSERT -- when your script shows the vim mode itself.

Claude Code picks the change up as soon as you save the file; no restart needed.

What your script receives

The script gets one JSON object on standard input each time it runs. The fields most people use (full list):

Three things to know:

• Limits only on Pro and Max. rate_limits appears for claude.ai Pro and Max subscribers, after the first response in a session, and each window can be missing. The docs don’t list it for Team, Enterprise or API keys. Read it with // empty so the script doesn’t break without it.
• The cost isn’t your bill. On a subscription, total_cost_usd is what the session would cost on the API, worked out on your machine. It resets to $0 after /clear.
• Context counts input only. used_percentage is input tokens from the last response, so it can be null early on, and /context may show a bit more because it also estimates messages since. It’s measured against the full window, so it isn’t the point where auto-compact kicks in if you changed that. When to compact covers what to do as it fills.

A script for context and limits

This one shows the model, the context, and your two usage limits with the time the 5-hour one resets. It needs jq, which macOS includes; on Linux install it from your package manager.

~/.claude/statusline.sh

#!/bin/bash
# Model, context, and the 5-hour and weekly limits with the 5-hour reset time
input=$(cat)
model=$(jq -r '.model.display_name' <<<"$input")
ctx=$(jq -r '.context_window.used_percentage // 0 | floor' <<<"$input")
five=$(jq -r '.rate_limits.five_hour.used_percentage // empty | floor' <<<"$input")
reset=$(jq -r '.rate_limits.five_hour.resets_at // empty | strflocaltime("%H:%M")' <<<"$input")
week=$(jq -r '.rate_limits.seven_day.used_percentage // empty | floor' <<<"$input")

line="$model | context ${ctx}%"
[ -n "$five" ] && line="$line | 5h ${five}% (resets $reset)"
[ -n "$week" ] && line="$line | week ${week}%"
echo "$line"

Make it executable with chmod +x ~/.claude/statusline.sh and point command at it. It prints something like Opus 5.5 | context 42% | 5h 63% (resets 15:00) | week 28%, and just the model and context until the limits arrive. To test it without Claude Code, pipe in sample JSON: echo '{"model":{"display_name":"Opus"}}' | ~/.claude/statusline.sh.

Each echo becomes its own row, so you can split it over two lines, and ANSI codes such as \033[33m color it in terminals that support them. For what the limits mean and how they reset, see Claude Code usage limits explained.

When it updates

The script runs when the session starts and again when a new response arrives, after /compact, when the permission or vim mode changes, when a limit window resets, and on each refreshInterval tick. Claude Code waits 300 ms for changes to settle and runs the script once, and a new update cancels a run that’s still going, so keep it fast: cache slow things such as git calls in a file named after session_id. While the session sits idle nothing triggers it, which is what refreshInterval is for.

Ready-made status lines

If you’d rather not write a script, the docs point to two community projects, and a third is popular for cost tracking. All three are third-party code that runs on every update, so read what you install:

• ccstatusline: a configurable status line with themes and widgets for context, session cost and session and weekly usage. Its setup screen runs with npx -y ccstatusline@latest.
• starship-claude: the status line through Starship, installed as a Claude Code plugin.
• ccusage statusline (marked beta): session and daily cost, burn rate, and what’s left of the current 5-hour block.

VS Code, Claude Desktop and SSH

• VS Code. The extension’s documentation doesn’t mention the status line, and users report that the graphical panel doesn’t show it. Run claude in VS Code’s integrated terminal, or turn on the extension’s useTerminal setting, to get it.
• Claude Desktop has its own indicators instead: a Context card and a usage ring next to the model picker that shows your plan usage when clicked.
• Over SSH the script runs on the machine where Claude Code runs, so jq and git have to be installed there.

When it stays blank

• The script failed or printed nothing. The status line shows output only after the script exits with 0. Run claude --debug to see its errors.
• The folder isn’t trusted yet. The status line follows the same rule as hooks and stays blank until you accept the workspace trust dialog.
• It shows the wrong width. tput cols doesn’t work inside the script; read the COLUMNS variable instead.
• On Windows commands run through Git Bash when it’s installed, otherwise PowerShell. Use forward slashes in paths.

Where Meowdoro fits

We built Meowdoro, a focus timer around the MacBook notch, and on purpose it leaves your status line alone. The status line shows the session you’re in; Meowdoro shows every Claude Code and Codex session at once, each with a ring for how full its context is, and suggests /compact at your break for the one that’s filling up (how it shows agents). The two work well together if you run several sessions. Try it and tell us what’s missing.

Questions

How do I show context usage in the Claude Code status line?

Print context_window.used_percentage from the JSON your script receives, or run /statusline show context percentage with a progress bar and let Claude Code write the script.

Can the status line show my usage limits?

Yes, on Pro and Max: rate_limits.five_hour and rate_limits.seven_day give the share used and the reset time, from version 2.1.80. They appear after the first response in a session.

Does the status line use tokens?

No. The script runs on your machine and doesn’t call the API.

Why is my status line blank?

Usually the script: it exited with an error or printed nothing. The other common cause is a folder whose trust dialog hasn’t been accepted yet. claude --debug shows the script’s errors.

Does the status line work in the VS Code extension?

Not in the graphical panel, by users’ reports; the docs don’t say either way. Run claude in the integrated terminal to get it.

How is this different from the status line in Codex?

Codex’s /statusline lets you pick from built-in items, including its rate limits, rather than running a script. See how to check your Codex usage.

Related guides

• Claude Code usage limits explained

  The 5-hour and weekly limits on Pro and Max, /usage, and what to do at the limit.

• Claude Code /compact vs /clear vs a new session

  What survives /compact, and when a clean start is better.

• Running several Claude Code sessions without losing track

  Worktrees, names, one place to see them all, and how many is too many.

Sources: the Claude Code documentation on the status line, settings, commands, VS Code, Claude Desktop and the changelog; user reports in Claude Code’s issue tracker about VS Code and Desktop; the projects’ own pages. Read on October 30, 2026.