IntelligenceIntelligence

Your AI is busy. Know what it's up to.

See how much of your plan is left.

About 5 minutes ยท Claude Code on a Pro or Max plan, and jq (built into macOS 15 and later)

One line along the bottom of Claude Code with the model, the folder, how full the conversation is, and how much of your 5-hour and weekly limits you've used. It turns amber at 75% and red at 90%.

Tell your agent about this URL

Paste this into Claude, or any AI assistant that can read web pages. It explains the skill to you, checks it, and asks before installing anything.

Message for your assistant
Install the skill at https://intelligenceintelligence.io/skills/usage-line.md. First:
1. Read https://intelligenceintelligence.io/skills/usage-line/ and check the file says the same thing, without saving anything into my project. If it doesn't match, stop and tell me.
2. Tell me in a few lines what the skill does and what will happen, and give me the file's address so I can read it myself.
3. Wait for my go-ahead.
Install the file as it is, rather than writing your own version. If you can't install skills, follow the file directly instead. Afterwards, ask whether I want this explanation again next time I install a skill from intelligenceintelligence.io, and remember my answer.

The skill file is https://intelligenceintelligence.io/skills/usage-line.md. Read it before you run it, if you like: it's the same as this page.

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

  1. Check you have jq. Run jq --version in a terminal. macOS 15 and later include it. On Linux, install it from your package manager.

  2. 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.sh
    

    It's about 40 lines. It reads what Claude Code sends it and prints one line. It makes no network calls and writes no files.

  3. 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.

  4. 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.

5. Summarise

One line: what the file is, where the setting is, and how to undo it.