Customizing the Claude Code status line
Claude Code can show a status line at the bottom of the terminal: a thin bar that updates as you work. It is easy to ignore until you start hitting context limits or wondering what a session actually cost. The bar keeps that kind of signal in peripheral vision so the main transcript stays focused on the task.
This post is about how the status line fits into daily use and how to tune it.
Why bother
Most of the value is density without noise. A good status line answers quick questions you would otherwise ask the model or dig through logs for:
- Am I on the branch I think I am? Wrong repo or branch is a classic source of “why did that file change?” confusion.
- Which model is actually active? If you switch between Sonnet, Opus, or other profiles, the name in the bar is a sanity check.
- How hard am I pushing the context window? Token usage relative to the limit is the difference between “one more big paste” and a forced compaction or new session.
- What is this session costing? If you bill time or just want guardrails, a running USD total (often with thresholds) beats guessing from the dashboard later.
- Am I about to hit rate limits? Some setups show progress toward rolling windows (for example 5-hour and 7-day resets) so you are not surprised by a 429 mid-refactor.
None of that needs to live in the chat. The status line is a reasonable place for it.
Enable and configure
The straightforward path is the built-in flow inside Claude Code:
- At the prompt, run
/statusline. - Follow the short interactive setup: pick which fields you want (directory, Git branch, model name, tokens, cost, and so on, depending on what your build exposes).
- If you need something the wizard does not cover, you can point configuration at a custom shell script and own the formatting yourself.
Settings are stored in your user config, typically ~/.claude/settings.json, under a key such as statusLine (exact schema follows whatever version of Claude Code you run; if an upgrade changes keys, check the docs or /help for that release). Editing the file by hand is fine once you know the shape you want.
Custom scripts
Pointing statusLine at a script is the escape hatch when you want:
- Colors or icons consistent with your dotfiles
- Extra fields (hostname, kube context, task ID) that the stock wizard does not list
- Different layouts for narrow vs wide terminals
The script runs in your shell environment, so anything you can print in one line (or a few ANSI segments) is fair game. Keep it fast: the bar refreshes often; heavy git or network calls will make the UI feel sluggish.
What people commonly show
These are the usual suspects, not a mandatory checklist:
| Signal | What it gives you |
|---|---|
| Token usage | Distance to context limit; useful before large pastes or tool-heavy turns |
| Session cost | Running USD for the session; often yellow or red past thresholds you define |
| Model | Confirms Sonnet vs Opus (or other) without opening settings |
| Git | Branch and sometimes repo name; catches wrong-directory mistakes |
| Rate limits | Visual progress for rolling API windows when your setup exposes them |
Thresholds for cost (for example warn at $1, stronger warn at $5) are convention, not a standard. Pick numbers that match how you work.
Community options
If you do not want to maintain shell glue, there are community projects aimed at prettier or richer bars. Treat them like any third-party dotfile dependency: read what they execute, pin versions if you care about reproducibility, and assume they may lag Claude Code API or config changes.
- ccstatusline — TUI-oriented, many widgets; good if you want a dashboard feel in the bar.
- claude-statusline — Often cited as easy to install; emphasizes color-coded context and cost.
Practical tips
- Start minimal. Add fields only after you notice you are missing them. A crowded bar is as bad as a noisy chat.
- Match terminal width. Long Git branch names and paths truncate awkwardly; shorter labels or abbreviations help.
- Debug the script outside Claude. Run it in a normal shell and confirm exit code, speed, and output before wiring it into
settings.json. - After upgrades. If the bar disappears or shows errors after a Claude Code update, compare your
settings.jsonwith the current docs; keys and script contracts do change sometimes.
Closing thought
The status line is a small feature, but it is the right layer for operational awareness: money, limits, and identity of the session, always visible and out of the way. Spending ten minutes on /statusline or a short script often saves more than that on avoidable mistakes later.