claude-usage-limits 1.0.0

package/skills/usage-limits/references/how-it-works.md

@@ -0,0 +1,136 @@
+# Where the numbers come from
+
+Everything is read from local files. Nothing is sent anywhere, and no API key
+or token is read.
+
+## Sources
+
+### The limits
+
+`~/.claude.json`, key `cachedUsageUtilization`. Claude Code refreshes this
+during normal use, so it is usually a few minutes old at most. The shape:
+
+```json
+{
+  "fetchedAtMs": 1787522765060,
+  "utilization": {
+    "five_hour":  { "utilization": 2,  "resets_at": "2026-08-24T02:59:59Z" },
+    "seven_day":  { "utilization": 75, "resets_at": "2026-08-23T22:59:59Z" },
+    "extra_usage": { "is_enabled": false }
+  }
+}
+```
+
+`utilization` is a whole-number percentage. `resets_at` is when that window
+rolls over. Some plans also carry `seven_day_opus` and `seven_day_sonnet`;
+the report includes them when they are present.
+
+If the key is missing, run `/usage` once inside Claude Code. That is what
+populates it.
+
+The plan name comes from `oauthAccount.organizationType` in the same file.
+Current effort and model come from `settings.json` in the config directory.
+
+`CLAUDE_CONFIG_DIR` is honoured if set.
+
+Every surface writes here: the terminal CLI, the VS Code and JetBrains
+extensions, and the desktop app all share one config directory, and their
+sessions are counted together. Entries carry an `entrypoint` field (`cli`,
+`claude-vscode`) if you want to tell them apart, but the report does not
+filter on it.
+
+### The pace
+
+`~/.claude/projects/<project>/<session>.jsonl`. One JSON object per line.
+Assistant turns carry a usage record:
+
+```json
+{
+  "type": "assistant",
+  "timestamp": "2026-08-23T22:04:56.858Z",
+  "requestId": "req_011...",
+  "effort": "xhigh",
+  "message": {
+    "id": "msg_01...",
+    "model": "claude-opus-5",
+    "usage": {
+      "input_tokens": 2,
+      "cache_creation_input_tokens": 8049,
+      "cache_read_input_tokens": 24780,
+      "output_tokens": 2144,
+      "cache_creation": { "ephemeral_1h_input_tokens": 8049 }
+    }
+  }
+}
+```
+
+Files whose modification time predates the window are skipped. Turns are keyed
+by `message.id` plus `requestId` and counted once, because resuming or forking
+a session copies earlier turns into a new file.
+
+## The arithmetic
+
+Each turn is priced at published API rates. Cache traffic is a multiple of the
+input rate: 1.25x for a five-minute write, 2x for a one-hour write, 0.1x for a
+read.
+
+```
+turn        = (input + 0.1*cache_read + 1.25*write5m + 2*write1h) * input_rate
+            + output * output_rate
+
+spent       = sum of turns inside the window
+per_percent = spent / utilization
+left        = per_percent * (100 - utilization)
+turns_left  = (100 - utilization) / (recent_cost_per_turn / per_percent)
+headroom    = (100 - utilization) / (recent_dollars_per_hour / per_percent)
+```
+
+The window opens at `resets_at` minus its span: five hours, or seven days.
+Recent pace is measured over the last hour, or since the window opened if that
+is more recent.
+
+The self-calibration is the point. Nobody outside Anthropic knows what a
+subscription limit is worth in tokens, and it differs by plan. But if 75
+percent of the week corresponds to a measurable amount of local traffic, the
+remaining 25 percent is worth a quarter of that. The absolute dollar figures
+are an internal unit for that ratio. On a subscription plan you are not billed
+them, and they should not be read as a bill.
+
+## Where it is soft
+
+**Whole percent granularity.** The meter reports integers, so 2 percent is
+really somewhere in 1.5 to 2.5. At low readings the projection can be off by
+a quarter or more in either direction. The report flags this below 5 percent.
+Above about 20 percent it tightens up considerably.
+
+**One machine only.** Transcripts are local. Usage from another machine, from
+claude.ai, or from a cloud session counts against the same limit but leaves no
+local record. The percentages stay correct; the calibration reads low, which
+makes the remaining headroom look smaller than it is.
+
+**Deleted transcripts.** Same effect. Old session files get cleaned up, and
+anything cleaned up inside the seven-day window is invisible to the pace
+calculation.
+
+**List prices are a proxy.** The rate table is first-party API pricing. How a
+subscription plan actually meters usage is not published, and the weighting
+almost certainly is not exactly this. It is close enough for ratios, which is
+all it is used for.
+
+**A reset time can be in the past.** The cache refreshes when Claude Code
+talks to the API, so an idle spell leaves it behind. A window whose `resets_at`
+has passed has already turned over, and its cached percentage describes a
+window that no longer exists. Those are marked stale, excluded from the
+binding choice, and never used for projections, because treating one as
+current would report an empty budget at the exact moment the budget came back.
+
+**Pace is not a promise.** Turns left assumes the next turns look like the last
+hour's. A debugging spiral or a large file read breaks that assumption
+immediately. Re-run the report if the shape of the work changes.
+
+## Keeping it accurate
+
+The rate table in `scripts/usage.js` is a plain object at the top of the file.
+When new models ship, add a row. An unknown id falls back to the family it
+names (`opus`, `sonnet`, `haiku`, `fable`) and then to Opus rates, so a missing
+row degrades to an estimate rather than a crash.

package/skills/usage-limits/references/tactics.md

@@ -0,0 +1,170 @@
+# Spending less per turn
+
+Everything here works by shrinking one of three quantities: the tokens you
+resend, the tokens you generate, or the number of times you do either.
+
+## The part people get wrong
+
+A conversation is stateless. Every turn resends the entire conversation so
+far. Nothing is stored server-side between requests, so a file you read on
+turn 5 is re-sent on turns 6 through 60.
+
+That resend is cheap per token but not free. Cached prefix tokens bill at a
+tenth of the input rate, fresh input at the full rate, cache writes at 1.25x
+(five-minute) or 2x (one-hour), and output at five times the input rate. On
+Opus rates, a 100k-token context costs roughly five cents a turn just to be
+re-read, before the model generates anything.
+
+Two consequences follow, and they drive most of the list below:
+
+- **Context length is a recurring tax, not a one-off cost.** Dumping a large
+  file into context on turn 5 is not one expensive turn, it is a surcharge on
+  every turn after it.
+- **Output is the expensive direction.** Reasoning tokens are output tokens.
+  A turn that thinks for 4,000 tokens and edits one line costs more than a
+  turn that reads 20,000 tokens of cached context.
+
+## Levers, largest first
+
+### 1. Drop the effort level
+
+Effort controls how much the model reasons, and reasoning is output. Going
+from `xhigh` to `low` cuts the expensive half of the turn several times over.
+This is the biggest saving available that does not change what gets built.
+
+```
+node scripts/lowpower.js on          # writes effortLevel, remembers the old one
+/effort low                          # same change, applied to the running session
+```
+
+Keep high effort for the decisions that are hard to undo: schema changes,
+migrations, anything touching auth. Mechanical work does not need it.
+
+### 2. Move mechanical work to a cheaper model
+
+Per million tokens, input and output:
+
+| Model | Input | Output |
+| --- | --- | --- |
+| Opus 5 | $5 | $25 |
+| Sonnet 5 | $3 | $15 |
+| Haiku 4.5 | $1 | $5 |
+
+Renaming symbols, writing boilerplate tests, formatting, mechanical
+translation between two known formats: none of that needs the top model.
+Switch at a task boundary rather than mid-task, because a model switch
+invalidates the prompt cache and the rebuild can cost more than the saving on
+a short remaining task.
+
+### 3. Read less, and read it once
+
+- Line ranges instead of whole files. Grep with a result limit instead of
+  opening candidates one by one.
+- Pipe noisy commands through `head`, `tail`, or `grep`. A full `npm test`
+  dump or an untrimmed `git log` lands in context and stays there.
+- Never re-read a file to confirm an edit applied. The edit already failed
+  loudly if it did not.
+- Prefer `git diff --stat` before `git diff`. Usually the stat is the answer.
+
+### 4. Cut the tool surface
+
+Every connected MCP server's tool definitions sit in the system prompt of
+every single request. A handful of large servers can add tens of thousands of
+tokens to the prefix, on every turn, whether or not you use them. Disconnect
+the ones this project does not need with `/mcp` or `claude mcp`.
+
+`DISABLE_BUNDLED_SKILLS=1` trims the bundled skill catalogue for the same
+reason, if none of them are in use.
+
+### 5. Protect the cache prefix
+
+Cache reads are ten times cheaper than fresh input, and the cache matches on
+an exact prefix. Any byte that changes early invalidates everything after it.
+Things that invalidate it mid-session:
+
+- switching models
+- editing `CLAUDE.md` or project settings
+- connecting or disconnecting an MCP server
+- changing the tool set
+
+None of these are forbidden. Just do them at a session boundary instead of in
+the middle of a long run.
+
+### 6. Batch tool calls
+
+Independent calls belong in one message. Three greps in one turn cost one
+context resend. Three greps in three turns cost three, plus three rounds of
+reasoning and narration.
+
+### 7. Skip subagents when the context already exists
+
+A subagent starts with an empty context and re-derives what the main session
+already knows. That is worth paying for genuine fan-out across more material
+than one context can hold. It is not worth paying to answer a question the
+main session could answer directly.
+
+### 8. Stop failing loops early
+
+The single most expensive pattern is retrying a fix that does not work.
+Three blind attempts cost more than one turn spent reading the actual error.
+If the second attempt fails for a new reason, stop and re-read.
+
+### 9. End sessions at task boundaries
+
+Compaction reads the whole conversation and writes a summary, which is a
+full-price pass over everything. It is worth it compared to dragging a bloated
+context through another twenty turns, but a fresh session started from a short
+handoff note is cheaper than either.
+
+Write the handoff, exit, start clean.
+
+### 10. Specify the work properly the first time
+
+Underspecifying is the most expensive habit in the list, and it looks like
+saving. A vague instruction that produces the wrong thing costs the build, the
+review, the revert, and the rebuild. Two hundred tokens of precise
+instructions routinely save several thousand.
+
+## Environment knobs
+
+| Variable | Effect |
+| --- | --- |
+| `MAX_THINKING_TOKENS` | Hard ceiling on reasoning per turn. |
+| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Hard ceiling on response length. Too low truncates mid-answer. |
+| `DISABLE_BUNDLED_SKILLS` | Drops the bundled skill catalogue from the prompt. |
+| `DISABLE_NONESSENTIAL_TRAFFIC` | Suppresses background requests. Small effect. |
+
+Ceilings are blunt. Effort level gets you most of the same saving while
+letting the model still finish its sentence.
+
+## What does not save money
+
+**Clearing between related tasks.** A fresh session pays a fresh cache write
+and re-reads the same files. Clear at real boundaries, not every few turns.
+
+**Terse prompts.** See lever 10. The tokens saved on the instruction come back
+multiplied in rework.
+
+**Turning thinking off entirely.** On Opus 5 this has known failure modes: the
+model can write a tool call into its visible text instead of actually calling
+the tool, which fails silently and pollutes later turns. Lower the effort level
+instead. It is cheaper *and* it still works.
+
+**Asking for shorter answers when the cost is elsewhere.** If the spend is in
+tool results, prose length is rounding error. Check where it actually went
+before optimising the visible part.
+
+## Rough arithmetic
+
+Illustrative, not measured. A 60-turn session with about 80k tokens of cached
+context, on Opus rates:
+
+| | Per turn | Over 60 turns |
+| --- | --- | --- |
+| Re-reading cached context | $0.04 | $2.40 |
+| Output at high effort, ~2,500 tokens | $0.063 | $3.75 |
+| Output at low effort, ~700 tokens | $0.018 | $1.05 |
+
+Same work, same context, roughly 44 percent cheaper. Halving the context on
+top of that takes another $1.20 off. Neither change removes a single feature
+from what gets built.

package/skills/usage-limits/scripts/lowpower.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+'use strict';
+
+// Turns the expensive knobs down and remembers what they were.
+//
+// effortLevel is the setting behind the /effort picker. It drives how much
+// reasoning the model does per turn, and reasoning is billed as output
+// tokens, which are the priciest tokens in the request. Dropping xhigh to
+// low is the single largest per-turn saving available without changing
+// model or scope.
+//
+//   node scripts/lowpower.js status
+//   node scripts/lowpower.js on
+//   node scripts/lowpower.js on --effort medium --model sonnet
+//   node scripts/lowpower.js off
+//
+// The saved values live in usage-limits-lowpower.json inside the config
+// directory, so "off" puts back exactly what was there, including keys
+// that were not set in the first place.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+const MANAGED_KEYS = ['effortLevel', 'model'];
+const DEFAULTS = { effortLevel: 'low' };
+
+function configDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function settingsFile() {
+  return path.join(configDir(), 'settings.json');
+}
+
+function stateFile() {
+  return path.join(configDir(), 'usage-limits-lowpower.json');
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+// Replace through a temporary file so an interrupted run cannot leave
+// settings.json half written.
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = file + '.usage-limits-tmp';
+  fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  fs.renameSync(temp, file);
+}
+
+function parseArgs(argv) {
+  const args = { command: null, effort: null, model: null, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--dry-run') args.dryRun = true;
+    else if (arg === '--effort') args.effort = argv[++i];
+    else if (arg === '--model') args.model = argv[++i];
+    else if (arg.startsWith('--effort=')) args.effort = arg.slice('--effort='.length);
+    else if (arg.startsWith('--model=')) args.model = arg.slice('--model='.length);
+    else if (!args.command) args.command = arg;
+  }
+  if (!args.command) args.command = 'status';
+  return args;
+}
+
+// Work out the new settings without touching disk. Returns the object to
+// write, the state to remember, and a readable list of what moved.
+function planApply(settings, options, existingState) {
+  const current = settings || {};
+  const wanted = {};
+  const effort = options.effort || DEFAULTS.effortLevel;
+
+  if (EFFORT_LEVELS.indexOf(effort) === -1) {
+    throw new Error('unknown effort "' + effort + '", expected one of ' + EFFORT_LEVELS.join(', '));
+  }
+  wanted.effortLevel = effort;
+  if (options.model) wanted.model = options.model;
+
+  // A second "on" must not record the already-lowered values as the
+  // originals, or "off" would restore low power forever.
+  const saved =
+    existingState && existingState.previous ? existingState.previous : capture(current);
+
+  const next = Object.assign({}, current, wanted);
+  const changes = [];
+  for (const key of Object.keys(wanted)) {
+    const before = current[key] === undefined ? '(unset)' : current[key];
+    if (String(before) !== String(wanted[key])) {
+      changes.push(key + ': ' + before + ' -> ' + wanted[key]);
+    }
+  }
+
+  return {
+    settings: next,
+    state: { savedAt: new Date().toISOString(), previous: saved, applied: wanted },
+    changes,
+  };
+}
+
+// Snapshot only the keys this tool is allowed to touch. A key that was not
+// present is recorded as null so it can be removed again on restore.
+function capture(settings) {
+  const previous = {};
+  for (const key of MANAGED_KEYS) {
+    previous[key] = Object.prototype.hasOwnProperty.call(settings, key) ? settings[key] : null;
+  }
+  return previous;
+}
+
+function planRestore(settings, state) {
+  if (!state || !state.previous) {
+    return { settings: settings || {}, changes: [], restored: false };
+  }
+  const next = Object.assign({}, settings || {});
+  const changes = [];
+
+  for (const key of MANAGED_KEYS) {
+    const before = next[key] === undefined ? '(unset)' : next[key];
+    const target = state.previous[key];
+    if (target === null || target === undefined) {
+      if (Object.prototype.hasOwnProperty.call(next, key)) {
+        delete next[key];
+        changes.push(key + ': ' + before + ' -> (unset)');
+      }
+    } else if (String(before) !== String(target)) {
+      next[key] = target;
+      changes.push(key + ': ' + before + ' -> ' + target);
+    }
+  }
+
+  return { settings: next, changes, restored: true };
+}
+
+function describe(settings, state) {
+  const lines = [];
+  const current = settings || {};
+  lines.push('Low power    ' + (state ? 'on since ' + state.savedAt : 'off'));
+  lines.push('effortLevel  ' + (current.effortLevel || '(unset, defaults to xhigh)'));
+  lines.push('model        ' + (current.model || '(unset)'));
+  if (state && state.previous) {
+    const previous = state.previous;
+    const parts = MANAGED_KEYS.map(
+      (key) => key + '=' + (previous[key] === null ? '(unset)' : previous[key])
+    );
+    lines.push('will restore ' + parts.join('  '));
+  }
+  return lines.join('\n');
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const file = settingsFile();
+  const settings = readJson(file) || {};
+  const state = readJson(stateFile());
+
+  if (args.command === 'status') {
+    process.stdout.write(describe(settings, state) + '\n');
+    return 0;
+  }
+
+  if (args.command === 'on') {
+    const plan = planApply(settings, args, state);
+    if (!plan.changes.length && state) {
+      process.stdout.write('Already in low power. Nothing to change.\n');
+      return 0;
+    }
+    if (args.dryRun) {
+      process.stdout.write('Would change:\n  ' + (plan.changes.join('\n  ') || '(nothing)') + '\n');
+      return 0;
+    }
+    if (!state && fs.existsSync(file)) fs.copyFileSync(file, file + '.usage-limits-backup');
+    writeJson(file, plan.settings);
+    writeJson(stateFile(), plan.state);
+    process.stdout.write(
+      'Low power on.\n  ' + (plan.changes.join('\n  ') || '(nothing to change)') + '\n' +
+        'Applies to new sessions. For the session you are in, run /effort ' +
+        plan.state.applied.effortLevel + '.\n'
+    );
+    return 0;
+  }
+
+  if (args.command === 'off') {
+    if (!state) {
+      process.stdout.write('Low power is not on. Nothing to restore.\n');
+      return 0;
+    }
+    const plan = planRestore(settings, state);
+    if (args.dryRun) {
+      process.stdout.write('Would restore:\n  ' + (plan.changes.join('\n  ') || '(nothing)') + '\n');
+      return 0;
+    }
+    writeJson(file, plan.settings);
+    fs.unlinkSync(stateFile());
+    process.stdout.write(
+      'Low power off.\n  ' + (plan.changes.join('\n  ') || '(nothing to change)') + '\n'
+    );
+    return 0;
+  }
+
+  process.stderr.write('usage: lowpower.js [status|on|off] [--effort level] [--model name] [--dry-run]\n');
+  return 1;
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write('lowpower: ' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  main,
+  EFFORT_LEVELS,
+  MANAGED_KEYS,
+  parseArgs,
+  capture,
+  planApply,
+  planRestore,
+  describe,
+};