Claude Quota Guardian

Open source · Free · MIT

Don't lose your work or your tokens with Claude.

Let technology work for your business, not the other way around.

When you work for hours with Claude and the session fills up or the quota runs out, the work dies halfway through. Guardian prevents it: it saves where you were right before the cutoff and resumes on its own, with no re-explaining.

YOUR ACCOUNT'S REAL QUOTAsession + weekly → checkpoint
0%limit
Detects → Saves checkpoint → Resumes

You use Claude Code

Install it and stop losing long sessions.

  • Automatic checkpoint at your real quota limit (5h session + weekly), not an estimate.
  • Resume spending almost zero tokens: the checkpoint is dense and the session continues on its own.
  • Reads your real quota: session, weekly and per-model — the same number you see in the app.
  • Browser extension to watch your usage live (badge + popup).
  • Cache countdown: you know when your next message is about to pay for the whole context again, and one click does the handoff.
  • Free, MIT, any plan (Pro/Max/Team), cross-platform.
$ guardian 
git clone https://github.com/LeonardoIAConsult/claude-quota-guardian.git
cd claude-quota-guardian
npm install
node bin/install.js
# Guardian runs on its own: watches your real quota and stops at your limit.
# Checkpoint and resume are automatic.
# Activity report whenever you want:
node scripts/report.js
# Clean uninstall — only removes its own:
node bin/uninstall.js
node bin/uninstall.js --purge  # + deletes the checkpoints
View on GitHub → Coming soon to the Claude plugins directory (community)
★ Useful? Give it a star

You run a business and want AI

Guardian is proof that I know how to deploy AI that survives real work.

You don't need to understand how it works under the hood. What matters: if you or your team are going to lean on AI to work, someone has to do it right — so it adds hours instead of burning them. That's what I do.

I help you put AI (and Claude) into your workflow, or your team's, with strategy and no hype.

Book your diagnosis →

How it works, in 3 steps

  1. 01

    Detects the limit

    It watches your real Claude quota (session and weekly) in the background. When you hit your limit, it acts.

  2. 02

    Saves where you are

    It forces a checkpoint: what you were building, what worked, what didn't, and the exact next step.

  3. 03

    Resume spending almost nothing

    On reopening, Claude reads the checkpoint and continues on its own. Zero re-explaining, minimal tokens.

) Monitor NEW

See your usage live, in the browser

A Chrome, Edge and Brave extension that shows your real Claude quota — session, weekly and per-model— without opening Settings. It reads your own claude.ai session; it never touches tokens or secrets.

claude.ai
Click the shield ↗ to see your usage
  • One glance, zero clicks. The number in the toolbar is the % of your most-pressing window; hover it to see which one. Green, orange or red by how close you are to the cap. If claude.ai fails for a moment, the last reading stays, greyed out.
  • All three real windows. Session (5h) and weekly block; per-model limits (Fable) only warn — if one is spent, you keep going with another.
  • No tokens, no secrets. It uses the same call Claude's Usage screen makes, with your session cookies. Only permission: claude.ai.
  • Each session's cache. How many minutes the cache of your Claude Code sessions has left. A local program that only this extension can start reads it: project names and minutes, never your conversations.
Install the extension → Loads in 20 seconds: chrome://extensions → Developer mode → Load unpacked
) Savings NEW

How does Guardian save you tokens?

It warns you before the cache expires. While the cache is alive, your next message reads the whole context at a fraction of the price. Once it expires, it pays for all of it again. Per Anthropic's documentation, a cache read costs 10% of the normal input price (5% on Opus 5.5 and Sonnet 5.5, 2.5% on Fable 5.1), and writing it back costs 1.25 to 2 times the normal price. Nothing in Claude Code tells you when that happens. Guardian does.

1 · Cache
Countdown in the status line, in a bar above the prompt and in the extension. If you are about to step away for longer than what is left, press Traspaso (handoff): it saves the checkpoint, you clear and carry on with a small context.
2 · Checkpoint
Written dense, no filler: resuming costs few tokens and you re-explain nothing.
3 · Block
The agent stops spending quota on a session that is about to die mid-task.
4 · Model
With your quota in the risk band (85%) and a premium model, it suggests a cheaper one. It only suggests.

It is an estimate, and I say so: Anthropic does not expose when the cache expires. Guardian assumes 60 minutes on a Pro/Max plan and 5 on an API key, and you can pin it with cache.ttlMinutes. It warns you 5 minutes early. The idea came from a "token-saving kit" shared as an artifact: I audited it, kept the clock and wired it to the checkpoint so the button actually does the handoff.

) Architecture [01 / 05]

What it does under the hood

Every step is a real Claude Code hook — no magic, and you can read the code.

1

Measures, after every action

On each PostToolUse, check-usage reads your real quota from your account's usage endpoint: session (5h), weekly and per-model — the same number you see in Settings → Usage.

2

Stops at your real limit

When your quota (session or weekly) hits its cap, it writes pending.json, notifies the OS and blocks with PreToolUse: no more tokens on a doomed session. It only stops the terminal sessions that are at the limit; your Desktop or SDK routines keep running. Per-model limits (Fable) only warn.

3

Saves a dense checkpoint

/continuity-checkpoint writes checkpoint-<ts>.md: what you were building, what worked (with evidence), what didn't, and the exact next step. Then it ends the turn.

4

Watches for the reset

A background watcher (adaptive cadence 15→3→1 min) detects when your quota resets and tells you: "ready to continue".

5

Resumes on its own

When you reopen the project, SessionStart (resume-context) injects the checkpoint Guardian saved in its own folder. The agent announces the next step and continues — zero re-explaining. A file from the repo, or a link pointing outside, is never loaded automatically: you see the path and you decide.

·

Real signal, not an estimate

It reads your account-wide quota (session/weekly/per-model) — the same number you see in the app, not a local approximation. Works on any plan (Pro/Max/Team) and any OS (token from a file or the macOS Keychain).

No automatic relaunching: you decide when to reopen. Guardian only handles the save and the resume.

All local, in ~/.claude/session-continuity/<project>/ — your assistant reads them on reopen:

›checkpoint-<ts>.md ›pending.json ›state.json
) Confidence [02 / 05]

The checkpoint says how it knows

Guardian doesn't save a fuzzy summary. It classifies every task with the evidence behind it — so the next session trusts what's verified and doesn't retry what already failed.

One line from a real checkpointlib/report.js · L1
HTML report — evidence: lib/report.js:1 · verification: 4 tests ✓  DONE
DONE

With evidence of implementation and verification (test, command or output). A plan isn't enough: it needs proof of real work.

PARTIAL

Started, with what's missing spelled out. The next session knows exactly where to continue.

NOT DONE

TODO, a red test or a missing artifact. Marked pending — not marked done out of optimism.

DEFERRED

Your decision to pause + the condition to reopen. Guardian never reopens it on its own.

) Specs [03 / 05]

Hard facts

All verifiable in the repo. No promises the code doesn't keep.

Blocking
100% by real quota: session (5h) + weekly block; per-model (Fable) only warns.
Signal
Account-wide quota (session/weekly/per-model) from the usage endpoint — the same number your account sees, not an estimate.
Monitor
Browser extension (Chrome/Edge/Brave): live badge + popup + the cache of each session that still has one, named after its project, no tokens.
Cache
Countdown in 3 places (status line, bar above the prompt, extension) and a Traspaso (handoff) button.
Platforms
Windows (Task Scheduler) · macOS (launchd) · Linux (systemd/cron).
Install
One command · clean uninstall: doesn't touch your hooks.
Base
Version 1.1.8 · Node.js · MIT license · extension and bar in English and Spanish · 433 tests: 402 in CI on Windows, macOS and Linux (Node 18/20) and 31 for the cache bar.
Extensible
Adapter architecture; today OpenAI Codex CLI (notify-only).
Extra
Opus→Sonnet downgrade warning · "continue at my own risk" override · optional Telegram · HTML activity report.
Privacy
Runs local, your code never leaves · no account · no telemetry.
Release
The block lifts on its own once your real quota is back under the threshold. Never by a timer, never without a reading.
Checks
One per account, shared by all your projects; if it fails, it waits 2→4→8… up to 15 min instead of hammering.
Security
Never runs programs from the project folder · future-dated or damaged readings are discarded.
) Cases [04 / 05]

When it saves you

A long session that cuts off

You've been building for hours and the context fills up mid-task. Guardian saves the exact state; you resume without re-explaining a thing.

Quota running out blind

Your session (5h) or weekly quota runs out with no warning. Guardian stops you before burning tokens on a session that's going to die anyway.

Several projects at once

Each project has its own isolated checkpoint (by path hash). They never cross or overwrite each other.

You closed without saving

Someone called, you closed the terminal and the checkpoint was left pending. You don't get stuck: once your quota comes back, the block lifts on its own.

Automated routines running

You have tasks running on their own in Desktop or through the SDK. Guardian only stops the terminal session that's at the limit; your routines keep going.

You open a repo you don't know

Guardian never runs anything from the project folder, and on resume it never loads repo files as context. You see the path and you decide.

) Details [05 / 05]

FAQ & privacy

Does it switch my model or relaunch on its own?

No. It only saves and warns; you decide when to reopen. The downgrade warning (Opus→Sonnet) is exactly that, a warning — it doesn't change the model by itself.

Which plan does it work with?

Any Claude plan (Pro, Max or Team): it detects only your quota — session (5h), weekly and per-model — by reading the token of your own Claude Code session. By default blocking is 100% quota-driven; the context % can be enabled as a fallback if you work without subscription quota.

How do I see my usage without opening Settings?

With the browser extension (Chrome/Edge/Brave): a toolbar badge with the % of your most-pressing window and a popup with session, weekly and per-model. It reads your claude.ai session with your cookies — no tokens, no data to third parties.

What is the cache and why does it cost me tokens?

It is the copy Claude keeps of the start of your conversation after each message. While it is alive, the next message reads the whole context at a fraction of the price. Once it expires, it pays for all of it again. Guardian shows how many minutes it has left, and if you are stepping away for longer, the Traspaso (handoff) button saves the checkpoint so you carry on with a small context.

How long does the cache last?

By default, 5 minutes on the API, and there is a 1-hour one. Guardian assumes 60 minutes when your session has a Pro/Max plan quota and 5 on an API key. It is an estimate (Anthropic does not expose the expiry), so it warns you 5 minutes early, and you can pin the lifetime yourself.

What if I close without saving the checkpoint?

The block lifts on its own once a real reading of your quota is back under the threshold. If you need to keep going sooner, /guardian-continue lifts it for a while at your own risk. No timer ever lifts it blindly.

Does it stop my automated routines?

No. It only blocks the terminal sessions that are at the limit. Whatever runs in Claude Desktop or through the SDK keeps working; there Guardian only warns.

Does it touch my settings.json?

It merges its hooks without deleting yours. The uninstaller only removes its own and leaves the rest intact.

What about other AI providers?

It ships with notify-only monitoring of OpenAI Codex CLI (reads its local session logs). The adapter architecture lets you add more.

Privacy first

  • Runs local on your machine; reads the signals Claude Code already exposes there. Your code never leaves.
  • No account, no telemetry from Guardian. It's open source (MIT): you can read every line.
  • Connections it makes: your own account's usage endpoint at api.anthropic.com (with your token, only to read your quota) and Telegram, only if you enable it (the token lives in your local config, never in the repo). If you configure ccusage, npx may download it from npm.
  • The cache you see in the extension is read by a local program with no network that only Guardian's extension can start. It answers with project names and minutes, never paths or conversations.

Guardian in real use

I'm using it in my own work and documenting the results — checkpoints, cutoffs avoided and sessions resumed. Coming soon: real screenshots of its activity report.

leonardoantolinez.com