Stop your Claude Code sessions automatically when subscription usage reaches a threshold (default 90%), so a long-running agent never burns through the last slice of your 5-hour or 7-day quota while you are not watching.
Unofficial. Not affiliated with Anthropic.
Fable 5.1 | 5h:42.5% 7d:63% <- status line while usage is below the threshold
cc-usage-guard: 5-hour window at 91% (resets 2026-11-08T09:26:40Z). Threshold is 90%.
Session stopped to preserve remaining quota. Wait for the reset, or raise the
threshold via CLAUDE_USAGE_GUARD_THRESHOLD or ~/.claude/usage-guard/config.json.
Claude Code reports your subscription usage (rate_limits) to the status line
command on every refresh. cc-usage-guard turns that into a guard:
Claude Code TUI
|
| status line JSON (includes rate_limits.*.used_percentage)
v
statusline.sh --writes--> ~/.claude/usage-guard/usage.json
| |
| "Fable 5.1 | 5h:42% 7d:63%" | read on every tool call / prompt
v v
status bar guard-hook.sh (PreToolUse, UserPromptSubmit)
|
| usage >= threshold?
v
{"continue": false, "stopReason": "..."}
- statusline.sh records the
five_hour,seven_dayandspend_limitpercentages plus their reset times, and shows them in the status bar. If you already had a status line, its command is kept and run first; the usage figures are appended to its output. - guard-hook.sh runs before every tool call and every prompt you submit.
When a monitored window has reached the threshold it returns
continue: false, which stops the session with the reason shown above.
The hook fails open: if the state file is missing, older than one hour, or unreadable, the session continues.
- Claude Code 2.1 or newer, logged in with a claude.ai Pro, Max or Ultra
subscription. Claude Code sends
rate_limitsonly for these plans, so Team and Enterprise plans are not supported. - macOS or Linux,
bash3.2 or newer. jq1.6 or newer (brew install jq,sudo apt-get install jq).
curl -fsSL https://raw.githubusercontent.com/codenote-net/cc-usage-guard/main/install.sh | bashOr from a checkout:
git clone https://github.com/codenote-net/cc-usage-guard.git
cd cc-usage-guard
./install.shThe installer:
- Checks that
jqandclaudeare available. - Copies
statusline.sh,guard-hook.shanduninstall.shinto~/.claude/usage-guard/. - Backs up
~/.claude/settings.jsontosettings.json.bak-<timestamp>. - Saves any existing
statusLine.commandaspassthroughinconfig.json. - Registers the status line and the
PreToolUse/UserPromptSubmithooks.
Running it again is safe: nothing is duplicated and your config.json is kept.
Open a new claude session afterwards; running sessions do not reload settings.
To review the script before piping it to bash, open
install.sh.
Settings live in ~/.claude/usage-guard/config.json. Environment variables
override the file, which is handy for a one-off session:
CLAUDE_USAGE_GUARD_THRESHOLD=95 claude| Key | Default | Environment variable | Meaning |
|---|---|---|---|
threshold |
90 |
CLAUDE_USAGE_GUARD_THRESHOLD |
Stop when any monitored window reaches this used percentage. |
max_age_seconds |
3600 |
CLAUDE_USAGE_GUARD_MAX_AGE |
Ignore usage data older than this. Prevents stale data from blocking. |
windows |
["five_hour","seven_day"] |
CLAUDE_USAGE_GUARD_WINDOWS |
Windows to check. spend_limit can be added. Comma-separated in the env var. |
passthrough |
null |
Your previous status line command. Set by the installer. |
Other environment variables:
| Variable | Meaning |
|---|---|
CLAUDE_USAGE_GUARD_DIR |
Use a different state/config directory. |
CLAUDE_USAGE_GUARD_DEBUG |
Set to 1 to save the raw status line JSON to last-statusline.json. |
CLAUDE_CONFIG_DIR |
Honored like Claude Code does: settings and state go under this directory. |
The session ends with the stopReason shown above. To continue working:
- Wait for the reset. The reason includes the reset time of each window that is over the threshold.
- Raise the threshold for one session:
CLAUDE_USAGE_GUARD_THRESHOLD=100 claude, or permanently by editingthresholdinconfig.json. - Disable it by running the uninstaller (see below).
- Each window in
rate_limitscan be absent. Verified Ultra accounts have no 5-hour limit, so Claude Code sends onlyseven_dayand the guard effectively watches the 7-day window alone. Pro and Max accounts receive both windows.spend_limitappears only behind a Claude apps gateway that sets a spend limit. The status line shows whichever windows are present. - Usage is only recorded while an interactive terminal session (
claude) is running, because only the status line receivesrate_limits. Non-interactive runs (claude -p) and the desktop app do not update the state file. The hook ignores data older thanmax_age_seconds, so a stale file never blocks you. - The guard acts before a tool call or when you submit a prompt. It cannot interrupt a single long model response that is already streaming.
- Claude Code itself still enforces the real limits; cc-usage-guard only stops earlier so that some quota is left for you.
- Team and Enterprise plans, Windows, Homebrew/npm packaging and a background refresher for idle sessions are out of scope for now.
bash ~/.claude/usage-guard/uninstall.shor, without a local copy:
curl -fsSL https://raw.githubusercontent.com/codenote-net/cc-usage-guard/main/uninstall.sh | bashThe uninstaller removes only the hook entries and status line it added,
restores your previous status line command if there was one, backs up
settings.json first, and deletes ~/.claude/usage-guard/.
git clone https://github.com/bats-core/bats-core.git /tmp/bats-core
shellcheck install.sh uninstall.sh bin/*.sh test/test_helper.bash
/tmp/bats-core/bin/bats testTests run against a throwaway HOME, so your real ~/.claude is never touched.
CI runs ShellCheck and the test suite on Ubuntu and macOS (macOS uses the
system bash 3.2).