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

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

01

Detects the limit

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

Saves where you are

It forces a checkpoint: what you were building, what worked, what didn't, and the exact next step.
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 — green, orange or red by how close you are to the cap.
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.

Install the extension → Loads in 20 seconds: chrome://extensions → Developer mode → Load unpacked

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

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.

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. Per-model limits (Fable) only warn.

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.

Watches for the reset

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

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 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, no tokens.

Platforms

Windows (Task Scheduler) · macOS (launchd) · Linux (systemd/cron).

Install

One command · clean uninstall: doesn't touch your hooks.

Base

Node.js · MIT license · 198 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

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.

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

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.