claude-usage-limits 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "usage-limits",
+  "owner": {
+    "name": "Ridelink",
+    "url": "https://github.com/ridelink0"
+  },
+  "description": "Usage limit aware planning for Claude Code.",
+  "plugins": [
+    {
+      "name": "usage-limits",
+      "source": "./",
+      "description": "Reads how much of your Claude Code usage limit is left, converts it into turns of headroom, and plans the work to fit inside it.",
+      "category": "productivity",
+      "tags": ["usage", "limits", "cost", "planning"],
+      "license": "MIT"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "usage-limits",
+  "displayName": "Usage Limits",
+  "version": "1.0.0",
+  "description": "Reads how much of your Claude Code usage limit is left, converts it into turns of headroom, and plans the work to fit inside it. Includes a low power switch that keeps spending down even at high effort.",
+  "author": {
+    "name": "Ridelink",
+    "url": "https://github.com/ridelink0"
+  },
+  "homepage": "https://github.com/ridelink0/claude-code-usage-limits",
+  "repository": "https://github.com/ridelink0/claude-code-usage-limits",
+  "license": "MIT",
+  "keywords": [
+    "usage",
+    "limits",
+    "budget",
+    "cost",
+    "tokens",
+    "planning",
+    "effort"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ridelink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# usage-limits
+
+A Claude Code plugin that reads how much of your usage limit is left and plans
+the work to fit inside it.
+
+Claude Code already knows how much of your 5-hour and weekly limit you have
+spent. It caches the numbers locally and shows them when you ask. What it does
+not do on its own is notice that the job in front of it is bigger than the
+budget behind it, and adjust. This adds that: a report you can act on, and a
+set of rules for what to do when the answer is "not enough".
+
+## What it prints
+
+```
+Claude Code usage
+
+  Plan       Claude Pro
+  Snapshot   3m old
+  Settings   model=opus  effort=xhigh
+  Overage    off, work stops at the limit
+
+  Window           Used   Resets in      Left  Turns left
+  5-hour            62%      1h 40m    $46.00         ~88   <- binding
+  weekly            75%       2d 4h      $124        ~240
+
+  Recent pace   15 turns in the last hour, $0.164 per turn, effort xhigh
+  Measured      1,284 turns of local transcript
+
+The 5-hour limit is the binding one. At the current pace it runs out in about
+1h 12m, which is 28m short of the reset. Size the work to fit, or slow the burn.
+```
+
+`Turns left` is the column that matters. It divides the remaining headroom by
+what a turn has actually been costing over the last hour, on your account, at
+your effort level, so it moves when your working style does. Fifteen turns of
+headroom means something you can plan against; 75 percent does not.
+
+It also breaks the window down by model, with the token split behind it:
+
+```
+  Models in the 5-hour window
+    Model                   Turns    Tokens   Output   Share
+    claude-opus-5             159     27.0M     212k    100%
+    Tokens  input 318, cache write 631k, cache read 26.2M, output 212k
+```
+
+When more than one project has run inside the window it breaks that down too,
+so you can see which working directory actually spent the week:
+
+```
+  Projects in the weekly window
+    Project                 Turns    Tokens   Share
+    ...ideLink-Stuff-app      930     45.2M     78%
+    C--Users-OWNER            240     12.1M     22%
+```
+
+That split is usually the surprise. Almost all of it is cache reads, billed at
+a tenth of the input rate but paid again on every turn, which is why context
+length matters more than any single expensive message.
+
+The percentages and reset times come from Claude Code's own cache. The pace
+comes from your local session transcripts. Neither requires a network call.
+
+## Install
+
+Nothing to install, if you just want the numbers:
+
+```
+npx claude-usage-limits
+npx claude-usage-limits --status
+npx claude-usage-limits lowpower on
+```
+
+That runs the same code as the plugin. Node 18 or newer.
+
+To have Claude read the numbers and plan against them, install it properly.
+
+As a plugin:
+
+```
+/plugin marketplace add ridelink0/claude-code-usage-limits
+/plugin install usage-limits@usage-limits
+```
+
+As a plain skill, if you would rather not use the plugin system:
+
+```
+git clone https://github.com/ridelink0/claude-code-usage-limits
+cp -r claude-code-usage-limits/skills/usage-limits ~/.claude/skills/usage-limits
+```
+
+On Windows, in PowerShell:
+
+```
+git clone https://github.com/ridelink0/claude-code-usage-limits
+Copy-Item -Recurse claude-code-usage-limits\skills\usage-limits "$env:USERPROFILE\.claude\skills\usage-limits"
+```
+
+Either way, ask something like "how much usage do I have left" or "can we
+finish this before the limit hits" and Claude will load it. Installed as a
+plugin it also gives you `/usage-limits:check`, which prints the report and
+sizes whatever you just asked for against it.
+
+The scripts also run on their own, with or without any of the above:
+
+```
+node skills/usage-limits/scripts/usage.js
+node skills/usage-limits/scripts/usage.js --json
+```
+
+## Credits, and what happens at the wall
+
+The report says which of two things happens when the plan allowance runs out,
+because they need opposite handling.
+
+If paid credits are off, work stops dead and there is no buying through it,
+so the report says so and plans around it. If they are on, the limit is a cost
+boundary instead of a wall. It deliberately does not warn you about that
+crossover, because Claude Code already announces it and asks before drawing on
+credits, and a second warning saying the same thing is just noise.
+
+When the binding window will run out before it resets, the report stops
+describing and starts instructing:
+
+```
+The 5-hour limit is the binding one. At the current pace it runs out in about
+20m, which is 3h 40m short of the reset. Size the work to fit, or slow the burn.
+  Work stops when it does. Nothing carries on into paid credits.
+  Land what exists, write the handoff, and resume after 03:00.
+```
+
+The clock time matters more than the countdown. "Resume after 03:00" is a
+plan; "4h 12m" is a number you still have to do arithmetic on.
+
+The skill also requires Claude to say up front when a job will not fit in what
+is left, name what it is doing now, what it is leaving, and when the rest can
+happen, rather than starting and stopping halfway through an edit.
+
+## Status line
+
+For a permanent readout instead of asking, point Claude Code's status line at
+the same script. In `settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node ~/.claude/skills/usage-limits/scripts/usage.js --status"
+  }
+}
+```
+
+It prints one line and prefixes `LOW` once a window passes 90 percent:
+
+```
+5h 62% 1h 40m  wk 75% 2d 4h
+```
+
+`--status` reads only the cached percentages and never opens a transcript, so
+it runs in about a tenth of a second and is safe on every redraw. Use the full
+path rather than `~` if your shell does not expand it, and point it at the
+plugin copy instead if that is how you installed it.
+
+## Plans
+
+It reads which plan you are on and adjusts what it tells you, because the
+advice differs even though the arithmetic does not:
+
+| Plan | Read from | What changes |
+| --- | --- | --- |
+| Pro | `claude_pro` | Smallest budget. The 5-hour window usually binds first. |
+| Max 5x | `claude_max` plus `default_claude_max_5x` | Room for Opus on most work. The weekly window is the one that bites. |
+| Max 20x | `claude_max` plus `default_claude_max_20x` | Rarely binds. No reason to slow down unless the weekly is already high. |
+| Team, Enterprise | `claude_team`, `claude_enterprise` | Seats are pooled and overage is an org setting. |
+
+The window maths never needs to know the plan. It calibrates against what your
+own account reports, so it is right on any tier, including ones that did not
+exist when this was written. The plan only decides which line of advice you
+get at the bottom of the report.
+
+## Where it works
+
+Every surface of Claude Code on a machine shares one config directory, so
+this reads all of them and does not care which one you are in:
+
+| Surface | Works | Notes |
+| --- | --- | --- |
+| Terminal (`claude`) | yes | |
+| VS Code extension | yes | |
+| JetBrains extension | yes | |
+| Desktop app | yes | |
+| Headless (`claude -p`) | yes | Scripts run fine, but there are no slash commands, so `lowpower.js` is the only way to change effort. |
+| Cloud and web sessions | partly | Those run on a remote machine with their own config directory. Percentages are per-account and stay correct; the pace is measured from whatever transcripts are local to wherever you run the script. |
+
+Sessions from different surfaces land in the same `~/.claude/projects` tree
+and are counted together. On this machine the transcripts carry both `cli` and
+`claude-vscode` entrypoints, and the report totals both.
+
+Windows, macOS, and Linux all work. `CLAUDE_CONFIG_DIR` is honoured if you have
+moved the config directory.
+
+## Working cheaply on purpose
+
+Half the problem is measurement. The other half is that a high effort setting
+keeps spending at the same rate whether or not there is room left.
+
+```
+node skills/usage-limits/scripts/lowpower.js status
+node skills/usage-limits/scripts/lowpower.js on                 # effortLevel -> low
+node skills/usage-limits/scripts/lowpower.js on --effort medium --model sonnet
+node skills/usage-limits/scripts/lowpower.js off                # puts back what was there
+```
+
+It edits `effortLevel` in `settings.json` through a temporary file, saves the
+previous values alongside, and keeps a `.usage-limits-backup` copy of the original.
+Keys it does not manage are left untouched. Running `on` twice does not
+overwrite the saved originals.
+
+The file change applies to new sessions. For a session already running,
+`/effort low` does the same thing immediately.
+
+That covers the setting. The larger saving is behavioural, and the skill file
+spells it out: batch tool calls, read line ranges instead of whole files, skip
+subagents when the context already exists, stop retrying a fix that is not
+working. Effort level does not control any of that, which is why those rules
+apply even at `xhigh` or `max`. The reasoning behind each one is in
+[tactics.md](skills/usage-limits/references/tactics.md).
+
+## Requirements
+
+Node 18 or newer, and a Claude Code recent enough to write
+`cachedUsageUtilization` into `~/.claude.json`. If the report says it found no
+snapshot, run `/usage` once inside Claude Code and it will be there.
+
+Nothing is uploaded. No API key, token, or credential is read. Everything comes
+from files already on the machine.
+
+## How accurate is it
+
+Good enough to plan with, not a bill. The honest caveats:
+
+- The meter reports whole percent, so a reading of 2 percent is really
+  somewhere between 1.5 and 2.5. Low readings project badly, and the report
+  says so when it is in that range.
+- Transcripts are local. Usage from another machine or from claude.ai counts
+  against the same limit but leaves no local record, which makes the estimate
+  read low.
+- The dollar figures are an internal unit used to convert your token mix into
+  a percentage of the limit. On a subscription plan you are not billed them.
+- Turns left assumes the next turns look like the last hour's. A debugging
+  spiral breaks that assumption immediately.
+- The cache only refreshes when Claude Code talks to the API, so after an idle
+  spell a window can sit past its own reset time. When that happens the report
+  says `stale` and the status line says `rolling` rather than reporting a
+  percentage for a window that has already turned over.
+
+[how-it-works.md](skills/usage-limits/references/how-it-works.md) has the field
+names, the formulas, and the rest of it.
+
+## Layout
+
+```
+.claude-plugin/plugin.json        plugin manifest
+.claude-plugin/marketplace.json   lets the repo serve itself
+skills/usage-limits/SKILL.md            what Claude reads
+skills/usage-limits/scripts/            the two scripts
+skills/usage-limits/references/         the longer notes
+test/                             node --test, no dependencies
+```
+
+## Tests
+
+```
+node --test
+```
+
+72 tests over the pricing, the window arithmetic, plan and credit detection,
+the status line, per-project attribution, the CLI, and the settings
+save/restore.
+
+## Status
+
+It works and I use it daily.
+
+What I am not doing is fielding feature requests or support questions. If you
+want it to behave differently, fork it and change it, which is what the MIT
+licence is there for. Do not wait on me to add something for you.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+
+// One entry point for the npm package. The plugin and skill call the scripts
+// under skills/usage-limits/scripts directly; this just gives npx users a
+// single command that reaches the same code.
+
+const HELP = `claude-usage-limits - how much Claude Code usage is left, and whether the job fits
+
+  claude-usage-limits                     the report
+  claude-usage-limits --json              the same numbers, machine readable
+  claude-usage-limits --status            one short line, for a status line
+
+  claude-usage-limits lowpower status     show the current effort setting
+  claude-usage-limits lowpower on         lower effortLevel, remembering the old value
+  claude-usage-limits lowpower on --effort medium --model sonnet
+  claude-usage-limits lowpower off        put back exactly what was there
+
+Reads the usage figures Claude Code already caches locally, plus your session
+transcripts, to report the remaining headroom as turns of work. Nothing is
+uploaded and no credentials are read.
+
+  https://github.com/ridelink0/claude-code-usage-limits
+`;
+
+function run(argv) {
+  const args = argv || [];
+
+  if (args.indexOf('--help') !== -1 || args.indexOf('-h') !== -1) {
+    process.stdout.write(HELP);
+    return Promise.resolve(0);
+  }
+
+  if (args.indexOf('--version') !== -1 || args.indexOf('-v') !== -1) {
+    process.stdout.write(require('../package.json').version + '\n');
+    return Promise.resolve(0);
+  }
+
+  if (args[0] === 'lowpower') {
+    const lowpower = require('../skills/usage-limits/scripts/lowpower.js');
+    return Promise.resolve(lowpower.main(args.slice(1)));
+  }
+
+  const usage = require('../skills/usage-limits/scripts/usage.js');
+  return Promise.resolve(usage.main(args));
+}
+
+if (require.main === module) {
+  run(process.argv.slice(2)).then(
+    (code) => {
+      process.exitCode = code || 0;
+    },
+    (err) => {
+      process.stderr.write(
+        'claude-usage-limits: ' + (err && err.message ? err.message : String(err)) + '\n'
+      );
+      process.exitCode = 1;
+    }
+  );
+}
+
+module.exports = { run, HELP };

package/commands/check.md

@@ -0,0 +1,14 @@
+---
+description: Report how much Claude Code usage limit is left and how many turns of work it buys
+---
+
+Run the usage report and read it back to me.
+
+1. Run `node "${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/usage.js"`.
+2. Tell me which window is binding, how many turns of headroom is left, and
+   whether that window resets before the budget runs out.
+3. If I have already said what I want built, size it against the turns left
+   and say whether it fits. If it does not fit, say what to cut rather than
+   starting and hoping.
+
+Report the numbers and stop. Do not start other work as part of this command.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "claude-usage-limits",
+  "version": "1.0.0",
+  "description": "See how much of your Claude Code usage limit is left as turns of work rather than a percentage, and plan the job to fit inside it.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "usage",
+    "limits",
+    "rate-limit",
+    "tokens",
+    "cost",
+    "budget",
+    "statusline",
+    "cli"
+  ],
+  "homepage": "https://github.com/ridelink0/claude-code-usage-limits",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ridelink0/claude-code-usage-limits.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ridelink0/claude-code-usage-limits/issues"
+  },
+  "license": "MIT",
+  "author": "Ridelink (https://github.com/ridelink0)",
+  "bin": {
+    "claude-usage-limits": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "commands/",
+    ".claude-plugin/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "usage": "node bin/cli.js"
+  }
+}

package/skills/usage-limits/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: usage-limits
+description: Check how much of the Claude Code usage limit is left and plan the work to fit inside it. Use before starting anything long, when the 5-hour or weekly limit is getting close, when asked how much usage is left or whether there is enough left to finish, and when asked to work cheaply, burn fewer credits, or stretch the rest of the limit.
+---
+
+# usage-limits
+
+Running out of limit halfway through a job is a scheduling failure, not bad
+luck. The numbers are on disk before the work starts. Read them, size the job
+against them, and either commit to finishing or cut the job down until it fits.
+
+## 1. Measure
+
+```
+node scripts/usage.js
+```
+
+Paths here are relative to this skill's own directory, not the project you are
+working in. Run them from there, or prefix them with the skill's path.
+
+It prints the real percentages and reset times from the CLI's own cache, plus
+a pace measured from the local session transcripts:
+
+```
+  Window           Used   Resets in      Left  Turns left
+  5-hour            62%      1h 40m     $46.0         ~88
+  weekly            75%       2d 4h     $124         ~240   <- binding
+
+  Recent pace   15 turns in the last hour, $0.164 per turn, effort xhigh
+```
+
+`Turns left` is the number that matters. It is the remaining headroom divided
+by what a turn has actually been costing over the last hour, on this account,
+at this effort level. Add `--json` when you want the raw fields.
+
+If it says no snapshot was found, run `/usage` once in Claude Code and try
+again. That populates the cache the script reads.
+
+The last line names the plan (Pro, Max 5x, Max 20x, Team, Enterprise) and what
+it means for spending. Pro has the least room and the 5-hour window usually
+binds first; Max 20x rarely binds at all. Take that line into account before
+deciding how careful to be.
+
+## 2. Size the job before starting it
+
+Count the work in turns, not in tasks. A rough scale that holds up in practice:
+
+| Work | Turns |
+| --- | --- |
+| Read and answer a question about existing code | 1 to 2 |
+| One edit plus the check that it worked | 2 to 4 |
+| A feature touching three or four files | 10 to 20 |
+| Debugging something with an unknown cause | 15 or more, and unpredictable |
+
+Then compare against `Turns left` and hold back a reserve. Reserve about a
+fifth of the budget for landing the work: the test run, the commit, and the
+handoff note. Work that gets cut off just before the commit is worth nothing,
+so the reserve is not optional.
+
+## 3. Decide, out loud
+
+Tell the user which of these applies before doing anything expensive.
+
+**It fits.** Say so with the number, then work normally. Do not slow down out
+of caution when there is room. Cheapness is not a virtue when the budget is
+not tight.
+
+**It fits only if nothing goes wrong.** Say so, switch to low power for the
+run, and reorder the work so the valuable part lands first.
+
+**It does not fit.** Say so before starting, in plain words. State that not
+all of it can be done in what is left, list what you are doing now and what
+you are leaving, and name the wall-clock time the window resets so the user
+knows when the rest can happen. Then do the part that fits, properly. Do not
+start and hope: half a feature, committed and working, beats a whole one
+abandoned mid-edit.
+
+**The window resets first.** If the reset lands before the budget runs out,
+the limit is not the constraint. Say that and stop optimising for it.
+
+## Credits
+
+The `Credits` line in the report says what actually happens at the limit, and
+the two cases need opposite handling.
+
+**Off.** Work stops dead at the limit. Nothing spills over. This is the case
+to plan hardest around, because there is no way to buy your way through it.
+
+**On.** The limit is a cost boundary rather than a hard stop, so a job that
+does not fit can still be finished, for money. Do not warn about the crossover
+yourself: Claude Code announces it and asks before drawing on credits, and
+repeating that only adds noise. Just factor it into the plan, and take the
+user's answer to that prompt as the decision.
+
+## 4. Low power
+
+Two halves, and the second one is the half that actually binds.
+
+The setting:
+
+```
+node scripts/lowpower.js on              # effortLevel -> low, old value saved
+node scripts/lowpower.js on --effort medium --model sonnet
+node scripts/lowpower.js off             # restores exactly what was there
+```
+
+In a headless run (`claude -p`) there are no slash commands, so the script is
+the only lever there.
+
+`effortLevel` is what the `/effort` picker writes. Reasoning is billed as
+output tokens, the most expensive tokens in the request, so dropping `xhigh`
+to `low` is the largest per-turn saving available without changing model or
+scope. The file change applies to new sessions; for the session already
+running, `/effort low` takes effect immediately.
+
+The behaviour, which applies **even at xhigh or max effort**, because the
+effort setting does not control any of it:
+
+- Think briefly on routine steps. Save the long reasoning for decisions that
+  are actually hard to reverse.
+- Send independent tool calls together in one message. Three calls in one turn
+  cost one context resend; three separate turns cost three.
+- Read line ranges, not whole files. Grep with a head limit. A 40k-token file
+  read is not paid once, it is paid again on every later turn in the session.
+- Never re-read a file to confirm an edit landed. The edit tool already failed
+  if it did not.
+- No subagents. A subagent starts cold and re-derives context that is already
+  in this session.
+- Nothing that was not asked for. No speculative refactor, no extra test, no
+  drive-by cleanup.
+- Fewer, denser turns. Narration between tool calls is output tokens spent on
+  nothing.
+
+`references/tactics.md` has the full list and the billing reasons behind each
+one.
+
+## 5. Checkpoint before the wall
+
+When the binding window is under roughly 15 percent, or under about ten turns
+of headroom, stop adding work and land what exists:
+
+1. Commit or otherwise save the working state.
+2. Write `HANDOFF.md`: what is done, what is next, which files are mid-change,
+   what the next session should read first.
+3. Say when the window resets, as a clock time and not just a duration, plus
+   what to run on the way back in.
+
+A handoff written with ten turns left is worth more than the tenth turn.
+
+## When to skip this skill
+
+Do not run the report on every prompt. Once at the start of a long piece of
+work, and again if the job grows or something starts looping. The report costs
+a turn, which is the thing it is trying to save.
+
+## Files
+
+| Path | What it is |
+| --- | --- |
+| `scripts/usage.js` | The report. `--json` for raw fields, `--status` for a one-line status line readout that skips the transcript scan. |
+| `scripts/lowpower.js` | `status`, `on`, `off`. Restores what it replaced. |
+| `references/tactics.md` | Every lever that lowers cost, and why it works. |
+| `references/how-it-works.md` | Where the numbers come from and where they are soft. |