AI Usage Tracker

Show Context Remaining in the Claude Code Status Line on Mac

Add a Claude Code status line that shows remaining conversation context on Mac, then test how it handles a missing reading and a reported zero.

Claude Code’s status line can show how much context your conversation has left. Early in a session, the percentage can be missing. Give that state its own label so a new session doesn’t look like it has 0% left.

On this page

1. Add the context reading

In Terminal, run command -v jq. If it returns no path, install jq first. Save the following as ~/.claude/statusline-context.sh. The script reads one field from the JSON Claude Code sends on standard input.

#!/bin/sh
jq -r '
  .context_window.remaining_percentage
  | if type == "number"
    then "Context \(.)% left"
    else "Context pending"
    end
'

Add statusLine to the top-level object in ~/.claude/settings.json, keeping your other settings. If you already have a custom line, save its command before replacing it or adapt its script to add the context reading.

{
  "statusLine": {
    "type": "command",
    "command": "/bin/sh \"$HOME/.claude/statusline-context.sh\""
  }
}

Claude Code runs the command in a shell and displays its output at the bottom of the terminal interface. You can also have Claude Code generate a status line with /statusline. Anthropic’s status line setup

2. Test the reading in Terminal

Paste these sample inputs into Terminal. They exercise the script without sending a prompt to Claude.

printf '%s\n' '{}' \
  '{"context_window":{"remaining_percentage":null}}' \
  '{"context_window":{"remaining_percentage":63}}' \
  '{"context_window":{"remaining_percentage":0}}' |
  /bin/sh "$HOME/.claude/statusline-context.sh"
Expected output from the sample
Missing or null
Context pending on the first two lines
Numeric reading
Context 63% left
Reported zero
Context 0% left

Open an interactive Claude Code session and check the line after your next response. If it stays blank even though the sample worked, check the script path, the JSON in settings.json, and whether the project overrides statusLine. Workspace trust and managed settings can also affect whether the command runs. Status line troubleshooting · Settings precedence

3. Read the percentage in context

The status line uses data from the most recent API response. /context can also estimate the space taken by messages added since that response, so the readings can differ. Use /context to see what is filling the window. For your subscription allowance and its reset times, use /usage. Context window fields · Claude Code commands