Ingestion

1. La carga del statusline de Claude Code

Esta es la ruta que no necesita trabajo extra una vez que Claude Code está conectado. Claude Code corre tu comando de statusline en cada render y escribe un objeto JSON que describe la sesión actual en la entrada estándar de ese comando. Cuando ese objeto lleva un bloque de límite de tasa, openlimiter statusline lo valida, lo escribe en la caché y renderiza los números frescos en la misma llamada.

{
  "rate_limits": {
    "five_hour": { "used_percentage": 23.5, "resets_at": 1738425600 },
    "seven_day": { "used_percentage": 41.2, "resets_at": 1738857600 }
  }
}

used_percentage es la parte de la ventana ya usada, de 0 a 100. resets_at es un número de época Unix en segundos, no una cadena de fecha. Ambos nombres de campo y la codificación de época vienen de la documentación publicada del statusline de Anthropic, no de este proyecto, y cada ventana es independientemente opcional: una carga que solo nombra una de ellas es un meter completo, no uno parcial.

• rate_limits aparece solo para suscriptores de Claude.ai en un plan Pro o Max, y solo después de la primera respuesta de API de una sesión. Una carga sin bloque rate_limits es la forma normal de una cuenta gratuita o una sesión que todavía no llamó a la API, no un error.
• Un reinicio implausiblemente lejano para su propia ventana, una ventana de cinco horas que reinicia días después, se descarta por su cuenta en vez de confiar en él. La otra ventana sigue contando.

Cualquier otra cosa en el objeto de sesión se ignora. Una ventana que falla la validación se descarta y la otra ventana sigue contando.

2. Un documento manual en disco

Escribe manual.json dentro del directorio de estado y cada orden lo recoge. Consulta configuración para ver dónde vive ese directorio en cada plataforma.

{
  "version": 1,
  "meters": [
    { "name": "MONTHLY", "used_percent": 61.5, "reset_at": "2026-08-29T12:11:29.714Z" }
  ]
}

Las reglas que debe cumplir cada fila

• name es un identificador en mayúsculas de hasta 32 caracteres, que empieza con una letra.
• used_percent es un número de 0 a 100.
• reset_at es un instante ISO en el futuro.
• Se leen hasta diez meters. Las filas después de la décima se ignoran.
• Una fila que rompe cualquiera de esas reglas se descarta, y las filas restantes siguen contando. Nada se repara.

Corre openlimiter snapshot --refresh para plegar el archivo dentro de la caché.

3. La orden genérica ingest

Cualquier script o agente le puede entregar a OpenLimiter un documento sin una integración de proveedor. La orden lee la entrada estándar, o un documento en línea pasado con --payload.

echo '{"meters":[{"name":"AGENT_BUDGET","used_percent":12.5,"reset_at":"2026-08-09T13:11:30.141Z"}]}' | openlimiter ingest

openlimiter ingest --payload '{"meters":[{"name":"AGENT_BUDGET","used_percent":12.5,"reset_at":"2026-08-09T13:11:30.141Z"}]}'

Sin una opción de proveedor, el documento se trata como un documento manual, así que la instantánea resultante queda etiquetada con precisión manual. Con --provider <id>, el documento se entrega al parser de ese connector y conserva las etiquetas de ese connector.

openlimiter ingest --provider codex --payload '{"rate_limits":{"primary_window":{"used_percent":33,"reset_at":"2026-08-09T14:11:30.264Z"}}}'

Los ids de proveedor válidos son claude, openrouter, codex, antigravity, opencode y manual. Un id desconocido es un error de uso y sale con 2.

Qué pasa con los datos

Las filas ingeridas se combinan en una sola caché bajo el mismo bloqueo que usa cualquier otro escritor, así que nada de lo que ya está en caché se pierde, y dos escritores que observan proveedores distintos no se pueden descartar filas entre sí en silencio.

• Los valores se validan contra el esquema de la instantánea antes de escribir nada.
• Los porcentajes se mantienen entre 0 y 100. Un valor fuera de ese rango no se recorta, se descarta.
• Cada escritura pasa por un reemplazo atómico, así que un lector observa el contenido anterior o el contenido nuevo, y nunca un archivo parcial.
• La vigencia se deriva de cuándo se observó una lectura y cuándo expira, así que los datos obsoletos quedan etiquetados en vez de reutilizarse en silencio como si fueran actuales.

¿Nada sobrevive la validación? La orden reporta que ningún meter acotado sobrevivió y sale con un fallo, en vez de escribir un marcador de posición.