VI EN
Claude Code

Claude Code status line: always see context %, cost and your 5-hour limit

Binh 3 min read Đọc bài này bằng tiếng Việt

TL;DR

The status line is a script that reads session JSON on stdin and prints one line. Showing context %, cost, 5-hour usage and model tells you when to compact or switch models mid-session.

Most Claude Code users only find out their context is nearly full when auto-compact suddenly kicks in, or find out what they spent when they open /usage at the end of the day. By then it's too late to change how you work. The status line fixes exactly this: a fixed line at the bottom of the screen, programmed by you, showing context %, session cost, git branch, your 5-hour limit… and updating continuously as you work. This post shows how to set it up in two minutes and what to display to save tokens.

How it works

The status line is any shell script. Whenever something happens (Claude finishes a reply, you switch model or mode…), Claude Code sends a JSON blob of session data on stdin, and whatever the script prints is what the status line shows. Bursts of updates are batched (300ms debounce) and an in-flight script is cancelled if a new update arrives, so it never slows the session down.

Fastest way: let Claude write it

/statusline show the model name, context % as a progress bar and session cost

Claude Code generates a script in ~/.claude/ and updates your settings. To remove it: /statusline delete.

Manual setup

In ~/.claude/settings.json:

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

A minimal script using jq (remember chmod +x):

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
FIVE=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
printf "%s | ctx %s%% | \$%.2f" "$MODEL" "$PCT" "$COST"
[ -n "$FIVE" ] && printf " | 5h %s%%" "$FIVE"

If you show a clock or data that changes while the session is idle (for example a background subagent touching git), add "refreshInterval": 5 to re-run it on a timer; the minimum is 1 second.

Fields worth showing

JSON fieldMeaningUse it to
context_window.used_percentage% of context usedKnow when to /compact or /clear before it's too late
cost.total_cost_usdEstimated session cost (list price)Get a feel for what each kind of prompt costs
rate_limits.five_hour.used_percentage% of the 5-hour limit (Pro/Max plans)Lower effort or switch model before you hit the ceiling
effort.level, model.display_nameCurrent effort and modelAvoid leaving Opus/max on for small chores
prompt_cacheCache hit ratio, last missSpot actions that break the cache
workspace.git_worktree, worktree.nameWhich worktree you're inTell parallel sessions apart
cost.total_lines_added/removedLines changedSee the size of the change at a glance

The default context window is 200K tokens (1M on models with extended context); context_window.context_window_size gives the actual number.

Design tips

  • Colour by threshold: context under 50% green, 50–80% yellow, above 80% red. One glance tells you it's time to clean up.
  • Multiple lines: if the script prints several lines, the status line shows several lines; line 1 for git, line 2 for context and cost.
  • Keep the script fast: avoid network calls or heavy git commands on every run; cache results in a temp file if needed.

Risks and caveats

  • The cost is a client-side estimate at list price, not your real bill; on a subscription it's only a reference.
  • With a custom status line, Claude Code hides some footer shortcut hints (such as "esc to interrupt").
  • The script runs with your permissions: don't paste scripts from the internet without reading them.

How to apply it

  • Dev: Install the minimal version now: model + context % + cost. Set yourself a rule: past 70%, compact or start a new session.
  • Tech Lead: Share a standard script with the team (including worktree and effort) so everyone "sees" cost, then compare habits.
  • PM: When you use Claude Code for documents, watch the 5-hour limit and move heavy work to another time window.

Sources & references

  1. Customize your status line — Claude Code Docs
More on Claude Code