Claude Quota Guardian

Open source · Gratis · MIT

No pierdas tu trabajo ni tus tokens con Claude.

Que la tecnología trabaje para tu negocio, no al revés.

Cuando trabajas horas con Claude y la sesión se llena o se agota la cuota, el trabajo muere a mitad de camino. Guardian lo evita: guarda dónde ibas justo antes del corte y lo retoma solo, sin re-explicar nada.

CUOTA REAL DE TU CUENTAsesión + semanal → checkpoint

0%límite

Detecta → Guarda checkpoint → Retoma

Usas Claude Code

Instálalo y deja de perder sesiones largas.

Checkpoint automático en tu límite real de cuota (sesión 5h + semanal), no una estimación.
Retomas gastando casi cero tokens: el checkpoint es denso y la sesión sigue sola.
Lee tu cuota real: sesión, semanal y por modelo — el mismo número que ves en la app.
Extensión de navegador para ver tu consumo en vivo (badge + popup).
Cuenta regresiva del caché: sabes cuándo tu siguiente mensaje va a volver a pagar todo el contexto, y con un clic haces el traspaso.
Gratis, MIT, cualquier plan (Pro/Max/Team), multi-OS.

$ guardian

git clone https://github.com/LeonardoIAConsult/claude-quota-guardian.git
cd claude-quota-guardian
npm install
node bin/install.js

# Guardian corre solo: vigila tu cuota real y frena en tu límite.
# El checkpoint y la retoma son automáticos.
# Reporte de actividad cuando quieras:
node scripts/report.js

# Desinstalación limpia — solo quita lo suyo:
node bin/uninstall.js
node bin/uninstall.js --purge  # + borra los checkpoints

Ver en GitHub → Próximamente en el directorio de plugins de Claude (comunidad)

Tienes un negocio y quieres IA

Guardian es la prueba de que sé implantar IA que aguanta el trabajo real.

No tienes que entender cómo funciona por dentro. Lo que importa: si tú o tu equipo van a apoyarse en IA para trabajar, alguien tiene que hacerlo bien — que sume horas, no que las queme. Eso es lo que hago.

Te ayudo a meter la IA (y Claude) en tu flujo o el de tu equipo, con estrategia y sin humo.

Agenda tu diagnóstico →

Cómo funciona, en 3 pasos

01

Detecta el límite

Vigila en segundo plano tu cuota real de Claude (sesión y semanal). Al llegar a tu límite, actúa.
02

Guarda dónde vas

Fuerza un checkpoint: qué construías, qué funcionó, qué no, y el próximo paso exacto.
03

Retomas gastando casi nada

Al reabrir, Claude lee el checkpoint y sigue solo. Cero re-explicación, mínimos tokens.

) Monitor NUEVO

Ve tu consumo en vivo, en el navegador

Una extensión para Chrome, Edge y Brave que muestra tu cuota real de Claude — sesión, semanal y por modelo— sin abrir Ajustes. Lee tu propia sesión de claude.ai; nunca toca tokens ni secretos.

claude.ai

Clic en el escudo ↗ para ver tu consumo

Un vistazo, cero clics. El número en la barra es el % de la ventana más apretada; al pasar el ratón te dice cuál es. Verde, naranja o rojo según qué tan cerca estás del tope. Si claude.ai falla un momento, se queda el último dato en gris.
Las 3 ventanas reales. Sesión (5h) y semanal bloquean; los límites por modelo (Fable) solo avisan — si se agota uno, sigues con otro.
Sin tokens ni secretos. Usa la misma llamada que la pantalla de Uso de Claude, con las cookies de tu sesión. Único permiso: claude.ai.
El caché de cada sesión. Cuántos minutos le quedan al caché de tus sesiones de Claude Code. Lo lee un programa local que solo esta extensión puede abrir: nombres de proyecto y minutos, nunca tus conversaciones.

Instalar la extensión → Carga en 20 segundos: chrome://extensions → Modo desarrollador → Cargar descomprimida

) Ahorro NUEVO

¿Cómo te ahorra tokens Guardian?

Te avisa antes de que el caché venza. Mientras el caché vive, tu siguiente mensaje lee todo el contexto a una fracción del precio. Cuando vence, lo paga entero otra vez. Según la documentación de Anthropic, leer del caché cuesta el 10 % del precio normal de entrada (5 % en Opus 5.5 y Sonnet 5.5, 2,5 % en Fable 5.1), y volver a escribirlo, entre 1,25 y 2 veces el precio normal. Nada en Claude Code te dice cuándo pasa. Guardian sí.

1 · Caché

Cuenta regresiva en la barra de estado, en una barra encima del prompt y en la extensión. Si vas a parar más de lo que queda, pulsas Traspaso: guarda el checkpoint, limpias y sigues con un contexto pequeño.

2 · Checkpoint

Escrito denso, sin relleno: retomar cuesta pocos tokens y no re-explicas nada.

3 · Bloqueo

El agente no sigue gastando cuota en una sesión que va a morir a mitad de tarea.

4 · Modelo

Con tu cuota en zona de riesgo (85 %) y un modelo premium, te sugiere uno más barato. Solo sugiere.

Es una estimación, y te lo digo: Anthropic no expone cuándo vence el caché. Guardian asume 60 minutos con plan Pro/Max y 5 con API key, y tú lo ajustas con cache.ttlMinutes. Avisa con 5 minutos de margen. La idea salió de un «kit de ahorro de tokens» que circulaba como artifact: lo audité, me quedé con el reloj y lo conecté al checkpoint para que el botón haga el traspaso de verdad.

) Arquitectura [01 / 05]

Qué hace por dentro

Cada paso es un hook real de Claude Code — nada de magia, y puedes leer el código.

Mide, tras cada acción

En cada PostToolUse, check-usage lee tu cuota real del endpoint de uso de tu cuenta: sesión (5h), semanal y por modelo — el mismo número que ves en Ajustes → Uso.

Frena en tu límite real

Cuando tu cuota (sesión o semanal) llega al tope escribe pending.json, notifica al sistema y bloquea con PreToolUse: no más tokens sobre una sesión condenada. Solo frena las sesiones de terminal que están en el límite; tus rutinas en Desktop o por SDK siguen. Los límites por modelo (Fable) solo avisan.

Guarda un checkpoint denso

/continuity-checkpoint escribe checkpoint-<ts>.md: qué construías, qué funcionó (con evidencia), qué no y el próximo paso exacto. Luego cierra el turno.

Vigila el reset

Un watcher en segundo plano (cadencia adaptativa 15→3→1 min) detecta cuándo tu cuota se reinicia y te avisa: «listo para continuar».

Retoma solo

Al reabrir el proyecto, SessionStart (resume-context) inyecta el checkpoint que Guardian guardó en su carpeta. El agente anuncia el próximo paso y sigue — cero re-explicación. Un archivo del repo, o un enlace que apunte afuera, nunca se carga solo: ves la ruta y decides tú.

Señal real, no estimada

Lee la cuota account-wide de tu cuenta (sesión/semanal/por-modelo) — el mismo número que ves en la app, no un cálculo local aproximado. Funciona en cualquier plan (Pro/Max/Team) y cualquier OS (token desde archivo o Keychain en macOS).

Sin relanzamiento automático: tú decides cuándo reabrir. Guardian solo se encarga del guardado y la retoma.

Todo local, en ~/.claude/session-continuity/<proyecto>/ — tu asistente los lee al reabrir:

›checkpoint-<ts>.md ›pending.json ›state.json

) Confianza [02 / 05]

El checkpoint dice cómo lo sabe

Guardian no guarda un resumen borroso. Clasifica cada tarea con la evidencia detrás — para que la próxima sesión confíe en lo verificado y no re-intente lo que ya falló.

Una línea de un checkpoint reallib/report.js · L1

reporte HTML — evidencia: lib/report.js:1 · verificación: 4 tests ✓ HECHO

HECHO

Con evidencia de implementación y verificación (test, comando o salida). No basta el plan: necesita prueba de trabajo real.

PARCIAL

Empezado, con lo que falta explícito. La próxima sesión sabe exactamente dónde seguir.

NO HECHO

TODO, test en rojo o artefacto ausente. Pendiente — no marcado como hecho por optimismo.

EN PAUSA

Tu decisión de parar + la condición para reabrir. Guardian no lo reabre solo.

) Specs [03 / 05]

Datos duros

Todo verificable en el repo. Sin promesas que el código no cumpla.

Bloqueo

100% por cuota real: sesión (5h) + semanal bloquean; por modelo (Fable) solo avisa.

Señal

Cuota account-wide (sesión/semanal/por-modelo) del endpoint de uso — el mismo número de tu cuenta, no una estimación.

Monitor

Extensión de navegador (Chrome/Edge/Brave): badge + popup en vivo + caché de cada sesión que lo tiene vivo, con el nombre de su proyecto, sin tokens.

Caché

Cuenta regresiva en 3 sitios (barra de estado, barra encima del prompt, extensión) y botón Traspaso.

Plataformas

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

Instalación

1 comando · desinstalación limpia: no toca tus hooks.

Base

Versión 1.1.8 · Node.js · licencia MIT · extensión y barra en español e inglés · 433 tests: 402 en CI en Windows, macOS y Linux (Node 18/20) y 31 de la barra del caché.

Extensible

Arquitectura de adaptadores; hoy OpenAI Codex CLI (notify-only).

Extra

Aviso de downgrade Opus→Sonnet · override «continuar bajo mi riesgo» · Telegram opcional · reporte HTML de actividad.

Privacidad

Corre local, tu código nunca sale · sin cuenta · sin telemetría.

Liberación

El bloqueo se suelta solo cuando tu cuota real vuelve bajo el umbral. Nunca por reloj ni sin una lectura.

Consulta

Una por cuenta, compartida por todos tus proyectos; si falla, espera 2→4→8… hasta 15 min en vez de insistir.

Seguridad

Nunca ejecuta programas desde la carpeta del proyecto · lecturas con fecha futura o dañadas se descartan.

) Casos [04 / 05]

Cuándo te salva

Sesión larga que se corta

Llevas horas construyendo y el contexto se llena a mitad de una tarea. Guardian guarda el estado exacto; retomas sin re-explicar nada.

Cuota agotándose a ciegas

Tu cuota de sesión (5h) o semanal se acaba sin avisar. Guardian te frena antes de quemar tokens en una sesión que va a morir igual.

Varios proyectos a la vez

Cada proyecto tiene su checkpoint aislado (por hash de ruta). No se cruzan ni se pisan entre sí.

Cerraste sin guardar

Te llamaron, cerraste la terminal y el checkpoint quedó pendiente. No te quedas trabado: cuando tu cuota vuelve, el bloqueo se suelta solo.

Rutinas automáticas corriendo

Tienes tareas que corren solas en Desktop o por SDK. Guardian frena solo la sesión de terminal que está en el límite; tus rutinas siguen.

Abres un repo que no conoces

Guardian nunca ejecuta nada desde la carpeta del proyecto, y al retomar no carga archivos del repo como contexto. Ves la ruta y decides tú.

) Detalles [05 / 05]

Preguntas y privacidad

¿Cambia mi modelo o relanza solo?

No. Solo guarda y avisa; tú decides cuándo reabrir. El aviso de downgrade (Opus→Sonnet) es exactamente eso, un aviso — no cambia el modelo por su cuenta.

¿Con qué plan funciona?

Con cualquier plan de Claude (Pro, Max o Team): detecta solo tu cuota — sesión (5h), semanal y por modelo — leyendo el token de tu propia sesión de Claude Code. Por defecto el bloqueo es 100% por cuota real; el % de contexto se puede activar como respaldo si trabajas sin cuota de suscripción.

¿Cómo veo mi consumo sin abrir Ajustes?

Con la extensión de navegador (Chrome/Edge/Brave): un badge en la barra con el % de la ventana más apretada y un popup con sesión, semanal y por modelo. Lee tu sesión de claude.ai con tus cookies — sin tokens ni datos a terceros.

¿Qué es el caché y por qué me cuesta tokens?

Es la copia que Claude guarda del inicio de tu conversación después de cada mensaje. Mientras vive, el siguiente mensaje lee todo el contexto a una fracción del precio. Cuando vence, lo vuelve a pagar entero. Guardian te muestra cuántos minutos le quedan, y si vas a parar más que eso, el botón Traspaso guarda el checkpoint para que sigas con un contexto pequeño.

¿Cuánto dura el caché?

Por defecto, 5 minutos en la API, y existe uno de 1 hora. Guardian asume 60 minutos si tu sesión tiene cuota de plan Pro/Max y 5 si usas API key. Es una estimación (Anthropic no expone el vencimiento), así que te avisa con 5 minutos de margen, y la duración la puedes fijar tú.

¿Y si cierro sin guardar el checkpoint?

El bloqueo se suelta solo cuando una lectura real de tu cuota vuelve bajo el umbral. Si necesitas seguir antes, /guardian-continue lo levanta un rato bajo tu riesgo. No hay reloj que lo suelte a ciegas.

¿Frena mis rutinas automáticas?

No. Solo bloquea las sesiones de terminal que están en el límite. Lo que corre en Claude Desktop o por SDK sigue funcionando; ahí Guardian solo avisa.

¿Toca mi settings.json?

Mergea sus hooks sin borrar los tuyos. El desinstalador solo quita lo suyo y deja el resto intacto.

¿Y otros proveedores de IA?

Hoy incluye monitoreo notify-only de OpenAI Codex CLI (lee sus logs de sesión locales). La arquitectura de adaptadores permite sumar más.

Privacidad primero

Corre local en tu máquina; lee las señales que Claude Code ya expone ahí. Tu código nunca sale.
Sin cuenta, sin telemetría de Guardian. Es open source (MIT): puedes leer cada línea.
Conexiones que hace: el endpoint de uso de tu propia cuenta en api.anthropic.com (con tu token, solo para leer tu cuota) y Telegram, solo si tú lo activas (el token vive en tu config local, nunca en el repo). Si configuras ccusage, npx puede descargarlo de npm.
El caché que ves en la extensión lo lee un programa local sin red que solo la extensión de Guardian puede abrir. Responde nombres de proyecto y minutos, nunca rutas ni conversaciones.

Guardian en uso real

Lo estoy usando en mi propio trabajo y documentando los resultados — checkpoints, cortes evitados y sesiones retomadas. Próximamente: capturas reales de su reporte de actividad.