Usage Meter: See Your Claude Code Limits in the Status Line
You get: Your Claude Code status line shows the model, context use and how much of your 5-hour and weekly plan limits you have used.
A free Claude Code kit that puts the model, context use and your 5-hour and weekly plan usage in the status line. One setup command, no tokens used.
By Claudekit Team Editor Tran Quang Dong Published Checked 2 min read
Test level
Smoke tested Claude Code actually loaded the kit and ran one scripted task in a capped run, and the result passed our checks. How we test- Tested with
- Claude Code 2.1.290
- Tested on
- Setup time
- About 3 minutes
- For
- Power users
Latest lab run: · Smoke tested · Claude Code 2.1.290 · 18 of 18 checks passed
Show checks
- Passed: files (9 files, 20262 bytes)
- Passed: manifest (usage-meter@0.1.1)
- Passed: manifest-paths (no custom paths)
- Passed: frontmatter (2 skills, agents and commands)
- Passed: hooks (no hooks)
- Passed: shell-syntax (4 scripts pass bash -n)
- Passed: secrets (11 Kiln Guard rules, no findings)
- Passed: network (every referenced host is allowlisted (pattern data not scanned: lab/test.sh))
- Passed: destructive (4 command surfaces pass Kiln Guard (pattern data not scanned: lab/test.sh))
- Passed: lab-spec (3 expectations, 2 scripts pass bash -n)
- Passed: marketplace (listed as usage-meter)
- Passed: plugin-validate (1 files valid, 0 warnings)
- Passed: kit-tests (lab/test.sh passed)
- Passed: smoke-fixture (lab/fixture.sh ready)
- Passed: smoke-run (3 turns, $0.0439)
- Passed: expect:file-exists (cfg/usage-meter-statusline.sh exists)
- Passed: expect:file-matches (cfg/settings.json matches usage-meter-statusline\.sh)
- Passed: expect:file-matches (cfg/settings.json matches "type": "command")
Install
In a Claude Code session, add the Claudekit marketplace once, then install:
/plugin marketplace add claudekit-ai/kits
/plugin install usage-meter@claudekitOr download the kit and start Claude Code in your project with it loaded for one session. No unzipping needed:
claude --plugin-dir ./usage-meter.zipOr load it straight from our site:
claude --plugin-url https://claudekit.ai/kits/usage-meter.zipA kit can run hooks with your permissions. Read its files before you install it.
Steps
- Install jq 1.6 or later (brew install jq or apt install jq)
- Download usage-meter.zip and start Claude Code with claude --plugin-dir ./usage-meter.zip
- Run /usage-meter:install and approve the one Bash command it asks for
- Send one message so Claude Code passes the rate_limits data to the status line
- To remove it later, run /usage-meter:uninstall
Usage Meter is a free Claude Code kit that shows your 5-hour and weekly plan usage right under the prompt. Load the plugin, run /usage-meter:install, send a message, and you get a line like this:
[Opus] ctx 8% | 5h 23% (resets 16:00) | week 41% (resets Thu 16:00)Each percentage turns yellow from 50% and red from 80%. It reads the rate_limits and context_window fields Claude Code passes to every status line, checked against the status line docs on 25 October 2026. It is the script from our statusline guide, packaged with an installer.
Plan note: the 5-hour and weekly numbers appear only on Pro and Max (or behind a Claude apps gateway with spend limits). On an API key you get the model and context only.
Setup, step by step
-
Install jq 1.6 or later.
-
Download usage-meter.zip.
-
Start Claude Code with the kit loaded:
claude --plugin-dir ./usage-meter.zipTo load it in every session, unzip it and move the
usage-meter/folder into~/.claude/skills/. -
Run the setup once:
/usage-meter:install
Why a setup step? A plugin cannot set statusLine itself; the plugin manifest reference says plugin settings accept only agent and subagentStatusLine. The skill copies the script to ~/.claude/usage-meter-statusline.sh, adds the statusLine entry, keeps every other setting and saves a dated backup of settings.json (for example settings.json.usage-meter-20261025-153000.bak). If you already have a status line it stops and asks before replacing it.
Permissions it needs
- Bash, once, to run the bundled
configure.sh. Claude Code asks first. - Writes
settings.jsonand one script in your Claude config directory. Nothing else. - No network calls, no hooks, no MCP servers.
What we tested
- Static: 28 checks. The status line prints the right line for a Pro/Max sample, an API-key sample with no
rate_limits, and a weekly-only sample. Colours switch at 50% and 80%. Install keeps other settings, writes a dated backup that a reinstall never overwrites, keeps a symlinkedsettings.jsonas a symlink, refuses to replace another status line without--force, handles a path with spaces, leaves invalid JSON untouched, and uninstall removes only its own entry. - Smoke: one real
claude -p "/usage-meter:install ./cfg"run on Claude Code 2.1.290 with Sonnet, on 25 October 2026. The script and thestatusLineentry were written to the target folder. Version 0.1.1 was smoke tested again by our lab on 26 October 2026 with the same scripted task, and passed. - Not tested: the rendered line inside an interactive session (status lines do not run in
-pmode), and Windows.
Uninstall
Run /usage-meter:uninstall, which removes the statusLine entry only if it points at this kit’s script. Then drop the --plugin-dir flag or delete ~/.claude/skills/usage-meter/.
Related
- Claude Code statusline: show your rate limit usage: the same script, explained line by line.
- Claude usage limits explained: what the 5-hour and weekly windows mean.
- How to reduce Claude token usage: what to do when the numbers climb.
Frequently asked questions
Why does the status line show only the model name?
Claude Code sends the 5-hour and weekly usage fields only to claude.ai Pro and Max subscribers, or behind a Claude apps gateway with spend limits, and only after the first response in a session. With an API key there are no plan limits to show.
Why does the kit need a setup command instead of working on install?
Plugins cannot set the statusLine setting. Plugin settings accept only agent and subagentStatusLine, so the kit copies its script next to your settings.json and adds the statusLine entry for you, with a backup.
Will it overwrite a status line I already have?
No. If another statusLine is configured, the install stops and shows it. It replaces it only if you rerun with --force, and it saves a dated backup of settings.json first.
Does the status line use my tokens?
No. The script runs locally on the JSON Claude Code already has and never calls the model.