What this does
A Pro or Max plan has two limits: a rolling 5-hour window and a weekly one. Run into either halfway through a long job and the job stops there.
So this puts them on screen all the time. Claude Code already knows both numbers and hands them to the status line, the bar along the bottom of the window. A short script prints them there:
Opus 5.5 | shop | ctx 43k | 5h 12% wk 45%
That's the model, the folder you're in, how much of the conversation's memory is in use, and how much of each limit has gone. It updates after every reply. The week is the one to watch.
What the colours mean
| part | amber | red |
|---|---|---|
ctx |
the conversation is 75% full | |
5h, wk |
75% of that limit used | 90% used |
When ctx turns amber, the conversation will soon be summarised to make room. That's a good moment to finish a step and start a fresh one. When wk turns amber, save the big jobs for after it resets.
Setting it up
-
Check you have jq. Run
jq --versionin a terminal. macOS 15 and later include it. On Linux, install it from your package manager. -
Download the script, read it, and put it in place.
mkdir -p ~/.claude curl -fsSL https://intelligenceintelligence.io/skills/usage-line/statusline.sh -o ~/.claude/statusline.sh less ~/.claude/statusline.shIt's about 40 lines. It reads what Claude Code sends it and prints one line. It makes no network calls and writes no files.
-
Point Claude Code at it. Add this to
~/.claude/settings.json, inside the outer braces:"statusLine": { "type": "command", "command": "bash ~/.claude/statusline.sh" }If the file already has a
statusLine, you have a status line of your own. Add the usage to it, as in the next section. -
Send one message. The line appears along the bottom. The usage part arrives after the first reply, because that's when Claude Code first hears the numbers.
If you already have a status line
Keep yours and add the usage to it. These two lines read the numbers:
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
Both are empty on plans without these limits, so print them only when they're there. The pct function in the script does the colouring if you want it too.
How to undo it
Remove the statusLine line from ~/.claude/settings.json and delete ~/.claude/statusline.sh. Nothing else was changed.
When this stops being a small job
It reads two numbers Claude Code already has. Showing usage across a team, or stopping work at a set point in the week, needs more than a status line. Ask for help with that.
Instructions for the assistant
You're helping someone add plan usage to their Claude Code status line. Be plain and brief, and change nothing without a yes.
1. Look first
Read ~/.claude/settings.json if it exists. Note whether it has a statusLine entry, and if so, read the script it runs. Run jq --version. Tell them in two or three sentences what you found.
Ask which plan they're on if it isn't clear. The usage numbers only exist on Pro and Max. On any other plan, say the line will show the model, folder and context only, and ask whether they still want it.
2. Put the script in place
If there's no status line yet, download the script as in step 2 of "Setting it up" and show it to them before going on. If ~/.claude/statusline.sh already exists, don't overwrite it. Save the new one as ~/.claude/statusline-usage.sh and use that path from here on.
If they already have a status line they like, offer to add the usage to it instead, as in "If you already have a status line". Show the exact lines you'd add and where, and add only those after a yes.
3. Change the settings
Show the exact change to ~/.claude/settings.json and wait for a yes. Edit the file so it stays valid JSON, keeping every other setting as it was. Check it with jq . ~/.claude/settings.json. If that fails, put the file back the way it was and say so.
4. Check it works
Run the script by hand with a sample:
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"'"$PWD"'"},"context_window":{"total_input_tokens":43210,"used_percentage":22},"rate_limits":{"five_hour":{"used_percentage":12},"seven_day":{"used_percentage":91}}}' | bash ~/.claude/statusline.sh
It should print one line ending 5h 12% wk 91%, with the 91 in red. Then ask them to look at the bottom of the window after your next reply.
- Nothing at the bottom: the settings file isn't valid JSON, or the path in
commandis wrong. jq: command not foundin the sample run: install jq.- No usage part after a reply: they're on a plan without these limits, or their Claude Code needs updating (
claude update).
5. Summarise
One line: what the file is, where the setting is, and how to undo it.