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.

SESSION CONTEXT / QUOTA98.6% → checkpoint
0%limit
Detects → Saves checkpoint → Resumes

You use Claude Code

Install it and stop losing long sessions.

  • Automatic checkpoint at 98.6% of the limit — with a predictive warning before the wall.
  • Resume spending almost zero tokens: the checkpoint is dense and the session continues on its own.
  • Real signal from your Pro/Max quota (5h/7d), not an estimate.
  • Free, MIT, cross-platform (Windows/macOS/Linux).
$ 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 and stops at 98.6%.
# 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 how much context and quota your session uses in the background. At 98.6%, 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.

) 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 the conversation context and your account's real rate_limits (5h/7d) quota.

2

Stops at 98.6%

Crossing the threshold, it writes pending.json, notifies the OS and blocks with PreToolUse: no more tokens on a doomed session.

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 full checkpoint. The agent announces the next step and continues — zero re-explaining.

·

Real signal, not an estimate

It uses the account-wide rate_limits that Claude Code exposes — the same number your account sees, not a local approximation.

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.

Threshold
98.6% of context and quota, with a predictive warning by tokens/min rate.
Signal
rate_limits 5h/7d account-wide — the same number your account sees, not an estimate.
Platforms
Windows (Task Scheduler) · macOS (launchd) · Linux (systemd/cron).
Install
One command · clean uninstall: doesn't touch your hooks.
Base
Node.js · MIT license · 191 tests (Node 18/20, CI).
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.
) 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

The 5h/7d limit 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.

) 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.

Does it work without a paid plan?

Yes: it monitors the conversation context even with no plan. With Pro/Max it also reads your real 5h/7d account quota.

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.
  • The only outbound = Telegram notifications, and only if you enable them (the token lives in your local config, never in the repo).

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.