New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Rate-limit window tracker that warns before limits hit and writes a shared machine-scope snapshot.

GitHub stars
32
View on GitHub

What it does

  • Adds a StopFailure hook that records rate-limit stops to a JSONL file, and a setup skill that verifies the plugin is working
  • Covers the subscription 5-hour and 7-day windows, with toasts at the 90% approach mark and 95% line threshold
  • Enforces opt-in behavior: Claude receives window lines only when model_notices is on, and loop lanes pause only when the operator opts in
  • Designed for autonomous loop lanes and sessions that need to plan around shared account rate limits

Rate-limit windows for loop lanes and Claude: a hooks module writes the subscription rate-limit windows to a fixed machine-scope file and toasts window changes (telling Claude too only with model_notices on, off by default), a StopFailure hook records rate-limit stops reactively, and a reader contract fixes how consuming sessions pause and resume.

Add marketplace

/plugin marketplace add melodic-software/claude-code-plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install rate-limits@melodic-software

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Readme

rate-limits

A Claude Code plugin that tells Claude, and every session on the machine that reads its file, where the account's shared subscription rate-limit windows stand, so Claude can plan around a limit before it hits one, and so autonomous loop lanes can report it and, where the operator opted in, pause before a limit and resume on their own after the reset. Three parts:

  • Hooks module (hooks/register.tsx), a mod that Claude Code runs in its own process. It shows you a toast when a window approaches or reaches the line threshold and when it resets, tells Claude the same at those boundaries when you turn on model_notices (off by default), can draw the figures in a band row (off by default), answers a status tool, and writes the windows to the fixed machine-scope file ~/.claude/rate-limits/rate-limits.json in interactive and headless sessions alike. It needs a Claude Code build that can run mods; older builds are unsupported. Pointer: when deciding which build that is, fetch mods overview: turn mods on or off live.
  • StopFailure hook (hooks/record-rate-limit-stop.sh), the reactive fallback. When a turn ends on a rate-limit API error, it appends a detection record to ~/.claude/rate-limits/stop-events.jsonl. The hook is side-effect-only by design: the record is its one output, and it returns no decision. Pointer: when deciding whether a StopFailure hook's output can do anything, fetch hooks: StopFailure live.
  • Reader contract (reference/reader-contract.md), the authoritative consumer contract: the fixed file path, the opt-in 95%-of-either-window pause threshold, the staleness rule, pause-end semantics, capability-detect fail-open, and drain-then-pause.

The module

The module tells Claude where the account stands against its rate limits, tells you when a window changes, can draw the figures in a band row, answers a status tool, and writes the contract file, in interactive, -p, --bg and /loop sessions alike. Tested with claude plugin test and live on Claude Code 2.1.288: interactive terminal sessions, -p runs, --bg and /loop lanes, side by side with the retired tee, a mods-off session, and native Windows. The Desktop app and VS Code were not run.

Lines to Claude

Lines go to Claude only with model_notices set to true; it is off by default, and then nothing from this plugin enters Claude's context. Claude can still read the windows from the status tool. With it on, a line goes to Claude only at a boundary, appended to the context of a main-thread tool result or of a prompt; a crossing seen when a turn ends reaches Claude with the next prompt. Per window (5-hour and 7-day), with the default options:

WhenLine
The window reaches the approach mark (90%)once per window, "at or above 90%", with the reset time
The window reaches the line threshold (95%)once per window, "at or above 95%", with the reset time
The window resets (its reset time passes, or it leaves the reading) after reaching the thresholdonce; the approach and threshold lines can then fire again
After a compaction (not the precompute kind), and after /resume or /branchthe verdict for each window at or above the approach mark, once; nothing when none is
After /clear, and when the module loads into a session that already has turns (a --resume launch, a reload after an options change, a hooks-worker restart)the verdict for each window at or above the threshold, once; nothing when none is
The signed-in account changes while a window is past quiet or a line is still dueonce, that earlier lines no longer apply, with each window's current reading, or "No reading yet for this account" before the new account's first response
A window's reset time reads more than a minute earlier than the recorded one while that window is past quiet or a line about it is still dueonce, that earlier lines for that window no longer apply, with its current reading

Use only rises within a window, so a reading that dips below a mark sends nothing and does not re-arm that mark's line. A restatement states the current reading, and none is made while that reading is below the restated mark. The account is the one in .claude.json, keyed on .oauthAccount.accountUuid, or on .oauthAccount.emailAddress when no UUID is there. When it changes, or a window's reset time moves earlier (which catches a switch the state file does not show, when the new account's window resets sooner), the module drops what it latched for the old account or window: levels, lines not yet sent, suggestions not yet handed to Claude, and toasts not yet shown. The reading held at an account change is the old account's, so it sets no level; the next reading that differs does. No other tool call or prompt carries a line. Each window gets its own line, for example rate-limits: 5-hour window at or above 95% (96% used), resets at 2026-10-03 21:00 UTC. A line states the window, the threshold crossed, and the use and reset time the line data selects. After the approach and threshold lines at a carrier comes one options line:

rate-limits: options: continue at the same model, effort and review depth; the user can switch accounts; or schedule work for after the reset. /usage shows what is using the plan (https://code.claude.com/docs/en/costs#track-your-costs). Usage never calls for lowering model, effort or review depth; whether to stop or pause is the user's call, or an opted-in loop lane's floor.

Facts alone led Claude to stop launching agents and to move work to a smaller model (#7118), so the line names the options and rules out trading quality for usage. A reset line carries no options line. Every line carries its verdict; rate_limit_line_data chooses what goes with it: the window's name (window), its use (percent) and its reset time (reset). Without window the line says "a rate-limit window". A line never carries the account email or the session name. Subagents get no line. Each line sent to Claude is also written as sent to the debug log (claude --debug). The line threshold is a line setting only: an opted-in loop lane's pause threshold stays 95% (see the reader contract).

Window changes shown to you

When a window rises from an earlier reading to the approach mark or the line threshold, or resets after reaching the threshold, the module shows a toast for 4 seconds, such as 5h at the 95% line threshold · resets 21:00 UTC, and writes one transcript line Claude does not read, ending · more: /rate-limits. A window's first reading since the module loaded or the window reset is never toasted, and neither is a restatement after a compaction, a resume, /clear or a reload: those only restate the verdict to Claude. Windows belong to the account, so a rise across /clear or a resume is a change and is toasted. The toast does not depend on model_notices. rate_limits_toast set to false drops the toast and keeps the transcript line. Outside the terminal (the Desktop app, VS Code, mobile), where toast drawing is unverified, the change also shows above the prompt, covering every window that changed, until your next prompt. The Desktop app draws one line per window with the percentage in color and the time left until it resets, plus Details and Dismiss buttons; other surfaces draw a single text row. Desktop's own usage ring holds the figures between changes.

The percentage's color comes from ~/.claude/rate-limits/levels.json, a file any reader can share, such as a status line: { "tiers": [50, 75, 90] } colors it yellow from 50, orange from 75 and red from 90, green below. The three tiers are whole numbers from 1 to 100 in ascending order. With no file, or one that breaks those rules, the defaults above apply. The tiers set colors only; when Claude is told stays with rate_limit_line_threshold.

Operator mode

With rate_limit_report_mode set to operator, a turn a person started by typing (or through the Remote Control bridge) gets no line. When that turn ends, the line is offered as the prompt box's suggestion (Tab takes it) and shown as a notice row above the prompt, on every surface, wrapped rather than cut off. With text in the box, only the notice row shows, and the suggestion is offered again once the box is empty. Where nobody can take a suggestion, the line goes to Claude as in automatic mode: -p and SDK turns, /loop and scheduled turns, task notifications and other non-typed turns, a session with no drawing surface (such as the VS Code panel), and a suggestion the session reports it cannot show. The row and a shown suggestion are your channel for a held line, so it gets a toast and a transcript line only when you never had either: its first offer could not show, or a survey hid the row until the line went to Claude. A suggestion that showed but was not taken goes to Claude as the automatic line at the next turn no person started; a turn a person starts drops it unsent.

Which apps draw the band's site, AbovePrompt, is upstream's render-sites table to say. The Desktop row was previewed in a Desktop 6.6695.0 session; no probe of this plugin ran in VS Code, so the band, the notice row, the toast and the suggestion there are untested.

  • Pointer: mods reference: render sites.
  • As of: 2026-10-03, Claude Code 2.1.288.
  • Recheck trigger: the AbovePrompt row changes the apps it lists, or a Desktop run of this plugin is made.

In operator mode, a --bg lane gets no line from its first turn; that line reaches Claude at the lane's next turn no person started. A lane that wants the lines at once supplies its own options when it starts its session, for example through --settings with the plugin's pluginConfigs entry: {"pluginConfigs": {"rate-limits@<marketplace>": {"options": {"rate_limit_report_mode": "automatic"}}}} (a --plugin-dir copy is keyed <name>@inline).

The /rate-limits command, band row and status tool

/rate-limits with no argument prints each window's use, verdict and reset time, the line threshold and approach mark, whether the band row and the toast are on, the snapshot path and a link to this README.

The band row above the prompt is off by default. When on, it shows rate-limits: 5h <x>% | 7d <y>%, with - for each window before the first reading. After it, a window the account does not report is left out: an account with no 5-hour limit shows only 7d <y>%. Context use is context-usage's row, not this one. rate_limits_band set to true turns it on for every session; /rate-limits band on, band off, or a bare band (toggle) changes it for the current session. Claude can call mcp__rate-limits__status for the exact figures from the last API response: every window the response reported, with its verdict, and, behind a Claude gateway, the spend_limit window, which is never written to the contract file.

Snapshot writes

The module writes ~/.claude/rate-limits/rate-limits.json through lib/write-snapshot.mjs, run with node, so the file is replaced atomically on Linux, macOS and native Windows. It writes at once when a window moves a whole point, appears, leaves or resets, and otherwise at most once every 300 seconds across the machine, checked from main-thread tool results, each measurement after a turn, a 60-second timer that runs only while a turn runs, and the session's end. It never writes from a turn a task notification started (a paused lane's own Monitor tick), and it follows the plugin's on/off switch and rate_limits_enabled. The body carries captured_at, session_id, the windows, and account.email only when the account in the state file at the write is the one it held at the last API response (a startup quota check counts); it never carries session_name or spend_limit. A session with no windows writes a windowless body, which never replaces a file that has windows.

Process cost: an event that writes nothing starts no process; each write starts one node process. Where the module cannot start that process, it writes nothing and logs that once to the debug log.

Where mods are off

Wherever mods are off for a session, whether the build is too old for mods or a setting, flag, policy or Claude Code itself turned them off, the module does not run: no lines, no band, no status tool, no module writes. The StopFailure hook still records, and readers fall back to reactive-only as the reader contract says. /rate-limits:setup check reports "mods off" in that case. bash "<plugin root>/scripts/check-mod-load.sh" reports it only for a build below the floor: a child process cannot see this session's flags or settings, so on a current build it prints PASS and tells the agent to look for the status tool in its own tool list. A hook that throws passes its event through unchanged.

Behavior

  • Atomic, last-writer-wins snapshot. Concurrent sessions write one path; readers never see torn JSON (temp file + rename, with a brief retry for the Windows rename-over-open-target case). The helper takes a short lock, refuses an older captured_at over a newer one, and keeps a windowless body from replacing windows. Last-writer-wins still applies between sessions: a session whose last API response is minutes old can write its older reading over a newer one, until the next write from a session with a fresher response.
  • Fail-open capability detection. Sessions whose auth exposes no subscription windows write a snapshot without rate_limits; consumers treat that as unknown and run reactive-only rather than throttling on fabricated data. Cloud / remote sessions typically have no file a consumer can read. That is the same unknown → reactive-only classification, documented as the expected degraded mode in reference/reader-contract.md ("Cloud / remote sessions"), with a documented residual that a live cloud producer is out of scope until one exists.
  • An unchanged reading costs no process. The module compares each reading with the last one it wrote and with the captured_at on disk, in process, so an unchanged reading inside the 300-second floor starts nothing. That floor is half the reader contract's 10-minute staleness budget, so a session whose windows sit still refreshes captured_at well before a reader could call it stale.
  • Multi-account operation is a narrowed gap. The snapshot names the account whose windows it carries in an account.email field, so a machine switching accounts is visible to a reader that checks it. Lanes drop a latched pause on an account change: while paused they read .oauthAccount.emailAddress from .claude.json directly and re-evaluate against the new account's windows. The gap that remains is attribution: the field is absent whenever the module could not attribute the observation, which covers an unreadable state file, no email-shaped value, and an account that changed between the last API response and the write. A lane that cannot attribute keeps its latch. The loop-lane convention §6 owns that framing; the reader contract states the absence cases and the untrusted-value rule (reference/reader-contract.md, "Snapshot file shape").

Tests and their budgets

claude plugin test plugins/rate-limits runs the module's suite (hooks/rate-limits.test.ts) with stubbed Claude Code calls; lib/write-snapshot.test.mjs covers the helper. The module's process budget, counted in the hook-budget convention's unit (one process start): 0 processes on a tool result, prompt, measurement or timer tick that writes nothing, and 1 (the node helper) per write, with writes at most once per changed reading and no more often than every 300 seconds when unchanged. The budget: test pins it: 50 unchanged tool results start no process, and one change starts exactly one.

The tests retired with the statusline tee, and what holds their property now:

Retired testReplacement
The tee suite: snapshot shape, account, no-change floor, enablementthe snapshot:, account:, floor: and switch: tests in hooks/rate-limits.test.ts
The tee suite: atomic write, windowless preservation, lockslib/write-snapshot.test.mjs
The tee suite: the zero-fork render tracethe budget: test, at the budget above
The bench lanes and their recorded process countsthe budget: test, at the budget above
The tee suite: transparency, spool and drain, async writes, the disabled markernone: the plugin no longer wraps a status line or spools
The shim and compose-script suitesnone: no shim ships; the setup skill's evals cover removing an old one

Install

/plugin marketplace add melodic-software/claude-code-plugins
/plugin install rate-limits@melodic-software

The module and the StopFailure hook need no wiring. /rate-limits:setup check verifies the result.

On a machine upgraded by hand from the plugin's earlier name, check reports the runtime directory left under that name as drift. Run /rate-limits:setup apply once no session runs the old plugin: it merges that directory's stop record into ~/.claude/rate-limits/stop-events.jsonl, older records first, and removes the directory.

Requirements

  • A Claude Code build at or above the terminal version mods need, with mods on, for the module. Below that floor, or with mods off, only the StopFailure hook runs, except on 2.0.15 through 2.1.75, which refuse the manifest, so nothing runs there. plugin.json declares the floor as engines["claude-code"], which only Claude Code 2.1.323 and later read, so prerequisites.json holds the same floor in detect.version.min of the entry with "id": "claude", which scripts/check-mod-load.sh compares against; the pointer below is where to re-derive it.

  • Node.js on PATH, installed on its own: the StopFailure hook launches through node hooks/exec-bash.mjs, and the module writes the file by running node, and we never count on Claude Code's install to provide it. Without it the hook records nothing and the module writes nothing, while its lines and band row still work.

  • Bash for the StopFailure hook: on native Windows, Git for Windows, which hooks/exec-bash.mjs finds.

  • Auth that exposes subscription windows, for proactive window data. On other auth the guard is reactive-only.

  • Pointer: when deciding which Claude Code version mods need, fetch mods overview: turn mods on or off live; when deciding whether a Claude Code install brings a Node.js the plugin could use, fetch advanced setup: install with npm live; when deciding which auth exposes subscription windows, fetch status line: rate limit usage live.

node "<plugin root>/lib/prerequisites.mjs" check "<plugin root>" reports whether node resolves, and bash "<plugin root>/scripts/check-mod-load.sh" whether the module can load. Both are read-only and install nothing.

Configuration

The userConfig options:

OptionWhat it controls
rate_limits_enabledKill switch for the StopFailure detection hook and the module's snapshot writes (default true). It does not stop the module's lines.
model_noticesThe module's lines to Claude, and the operator-mode suggestions (default false). Off, nothing from this plugin enters Claude's context; the toast, transcript line, band row, status tool and snapshot are unchanged.
rate_limit_report_modeautomatic (default) or operator, only with model_notices on; see Operator mode.
rate_limit_line_thresholdWindow use for the threshold line (default 95).
rate_limit_approach_pctWindow use for the one approach line (default 90).
rate_limit_line_dataWhat a line carries beside its verdict: percent, window, reset (default verdict,percent,window,reset).
rate_limits_bandThe band row (default false).
rate_limits_toastThe toast when a window nears or reaches the threshold or resets (default true); the transcript line stays either way.
account_switch_urlThe link the options line gives for switching accounts, as switch accounts (<url>) (unset: no link). A value that is not one http(s) URL reads as unset, with one transcript line naming it.

Two settings live outside userConfig:

SettingWhereDefaultWhat it controls
Snapshot file a status line can read~/.claude/rate-limits/rate-limits.json, written under rate_limits_enabledonA status-line command that reads this file keeps working with every other option at its default.
LOOP_LANE_RATE_LIMIT_PAUSEthe loop lane session's environmentunset (off)1 makes an unattended loop lane pause at 95% of either window; see the reader contract.

A threshold or approach mark outside 1 to 100, or line data with an unknown item, reads as that option's default with one transcript line naming it. The thresholds declare no range in userConfig; the module judges a value outside 1 to 100 itself. A value of the wrong type (text for a number, a number for a switch) is Claude Code's to handle before the module sees it.

The module reads its options when it loads, so a changed option applies from the module's next load. The StopFailure hook receives rate_limits_enabled as CLAUDE_PLUGIN_OPTION_RATE_LIMITS_ENABLED at session start.

  • Pointer: for when Claude Code reloads a module after its options change, read the doc comment on Register in the claude-code/index.d.ts types Claude Code writes for its build (see create: get the types for your build).

Set it with /plugin configure rate-limits@<marketplace>, or headless via claude plugin install rate-limits@<marketplace> -s <scope> --config rate_limits_enabled=false, run against the installed plugin. Never uninstall to reconfigure. The convention below records what that command prints and writes for an installed plugin; its verified-version record lives in the plugin-reconfiguration convention.

The file path and the 95% pause threshold an opted-in lane applies are deliberately not configurable: they are contract constants that cross-plugin consumers inline from the reader contract; a per-user override would silently split the writer from its readers. The kill switch stops this plugin's writes and records; turning the plugin off for a project is enabledPlugins, and removing it is uninstall.

Options reference

Generated from this plugin's .claude-plugin/plugin.json. For how Claude Code asks for these and hands them to the plugin, see User configuration.

OptionTypeDefaultDescription
rate_limits_enabledbooleantrueTurns on the StopFailure detection hook and the module's snapshot writes to the machine-scope rate-limit file. Lines to Claude have their own option. On by default. Read from managed settings first, then user settings.
model_noticesbooleanfalseSends Claude one line when a rate-limit window approaches or reaches the line threshold, when it resets, and after a compaction, a resume or a /clear at the threshold. Off by default; the toast, transcript line, band row, status tool and snapshot work either way.
rate_limit_report_modestring"automatic"Acts only with model_notices on. automatic (default) sends the lines to Claude; operator holds them in a turn a person typed and offers the person a ready-made prompt and a notice row above the prompt when the turn ends. Headless, loop and schedule turns get automatic lines either way.
rate_limit_line_thresholdnumber95Window use at which Claude gets the threshold line, 1 to 100; any other value reads as the default. Default 95, the pause threshold of a loop lane that opted in to pausing, which stays 95 whatever this is set to.
rate_limit_approach_pctnumber90Window use at which Claude gets one approach line before the threshold, 1 to 100; any other value reads as the default. Default 90; at or above the threshold, no approach line is sent.
rate_limit_line_datastring"verdict,percent,window,reset"Comma list of what a line carries beside its verdict, which every line has: percent, window and reset. Default verdict,percent,window,reset; a list with an unknown item reads as the default. Never the account email or the session name.
rate_limits_bandbooleanfalseDraws the 5-hour and 7-day window figures in a row above the prompt. Off by default. Turn it on in /config, or for one session with /rate-limits band on.
rate_limits_toastbooleantrueShows a toast and writes one transcript line when a rate-limit window nears or reaches the line threshold, or resets from it. Off keeps the transcript line. On by default.
account_switch_urlstring(none)One http(s) URL for how you switch Claude accounts, which the options line after an approach or threshold line names. Unset: the line says the user can switch accounts, with no link.

How to set these

Set the options above for rate-limits@<marketplace>, replacing <marketplace> with the marketplace you installed this plugin from:

Do not uninstall the plugin to reconfigure it: see What an uninstall deletes and keeps. For a Claude Code release without plugin configure, see Plugin install.

Upstream documentation

Consumers

Written for Claude in every session that loads the plugin and for the loop-lane convention's three lanes (work-items work-loop and attend-queue, source-control babysit-loop), which inline the reader contract's operable floor. Any session or tool on the machine may read the same files under the same contract.

License

MIT (SPDX-License-Identifier: MIT).

Details

Marketplace
melodic-software/claude-code-plugins
Source
plugins/rate-limits
Category
Claude Code

More from melodic-software/claude-code-plugins

All 139

Similar to rate-limits

More Automation & Workflows