Claude Code status line: how to set it up, and what to show

The status line is the row above Claude Code's footer. It runs a command you choose, pipes the session's state to it as JSON, and shows whatever the command prints. You can write that command, ask Claude Code to write it, or point it at a tool.

Set it up

The shortcut is the /statusline command inside Claude Code. Describe what you want, and Claude Code writes a script into ~/.claude/ and the setting for you:

/statusline show model name and context percentage

/statusline remove takes it out again. By hand, add a statusLine key to ~/.claude/settings.json (or a project's settings). type is always command; command is a script path or an inline shell command:

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

Or use Caprock's line:

What Claude Code passes in

The command runs when a session starts and again on each assistant message, after /compact, and on a few other changes, debounced at 300ms. If a new update arrives while your command is still running, Claude Code cancels it — so the command has to be fast.

What it cannot show

Everything on stdin is about this session, right now. A total across sessions or days needs something that has been keeping the record. That is what ccusage and Caprock add, in different ways. For a team, the record can also be an OpenTelemetry collector: Claude Code OpenTelemetry.

Caprock's status line

Here is the line on this session, with the Claude Code half of the input filled in by hand so it can be shown:

$ caprock statusline < sample.json
⛰ · Opus 5.5 · ctx 41% · $12.34 · 1842 turns · 1975 steps · cache −89% · 5h 23% resets 17:00 · 7d 61%

• Turns and steps — this session's turns and tool calls, from Caprock's own record.
• cache −89% — the share of the bill the prompt cache cut, computed the same way as the app's Cost screen. Not the hit rate: on my machine most sessions sit above 99%, so it barely moves — the two, measured side by side.

The line fits your terminal. When it is too wide, token totals go first, then the cache figure, then turns and steps; the model, context, cost and plan windows always stay. The plan windows are also sent to the app, so its Cost screen can show them — those numbers and the session id, nothing else from the JSON.

In the Caprock app, Settings → Status line picks the line: Full (the default) is all of the above; Short is model, context and the plan windows; Hidden prints nothing, so Claude Code gets its row back while the plan windows still reach Caprock; Off removes Caprock's entry from Claude Code's settings, never a line you set yourself.

ccusage or Caprock

If a day's total and a burn rate are what you want on the line, ccusage does that and Caprock does not. Caprock's line comes from the same record that holds every session on the machine, whether or not Caprock started it — who is waiting on you, how close each subscription is to its limit, what each pull request cost — kept past Claude Code's 30-day cleanup.

Troubleshooting

Caprock's counters need a read from its local daemon, with a 40ms budget; past that you get the plain line, and the command always exits cleanly. caprock statusline --plain turns the counters off. On Windows, Claude Code runs status line commands through Git Bash when it is installed, so Caprock writes its own path with forward slashes and quotes.