Ingestion

1. Die Claude Code Statusline Payload

Das ist der Weg, der keine zusätzliche Arbeit braucht, sobald Claude Code verdrahtet ist. Claude Code führt deinen Statusline Befehl bei jedem Rendern aus und schreibt ein JSON Objekt, das die aktuelle Session beschreibt, an die Standardeingabe dieses Befehls. Trägt dieses Objekt einen Rate Limit Block, validiert openlimiter statusline ihn, schreibt ihn in den Cache, und rendert die frischen Zahlen im selben Aufruf.

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

used_percentage ist der Anteil des Fensters, der schon verbraucht ist, von 0 bis 100. resets_at ist eine Unix Epoch Zahl in Sekunden, keine Datumszeichenkette. Beide Feldnamen und die Epoch Kodierung stammen aus Anthropics veröffentlichter Statusline Dokumentation, nicht aus diesem Projekt, und jedes Fenster ist unabhängig optional: Eine Payload, die nur eines davon nennt, ist ein vollständiger Meter, kein unvollständiger.

• rate_limits erscheint nur für Claude.ai Abonnenten auf einem Pro oder Max Plan, und erst nach der ersten API Antwort einer Session. Eine Payload ohne rate_limits Block ist die gewöhnliche Form eines kostenlosen Kontos oder einer Session, die die API noch nicht aufgerufen hat, kein Fehler.
• Ein Reset, der für sein eigenes Fenster unplausibel weit entfernt liegt, ein fünf Stunden Fenster, das erst Tage später zurückgesetzt wird, wird für sich verworfen statt geglaubt. Das andere Fenster zählt weiter.

Alles andere im Session Objekt wird ignoriert. Ein Fenster, das bei der Validierung durchfällt, wird verworfen, und das andere Fenster zählt weiter.

2. Ein manuelles Dokument auf der Festplatte

Schreib manual.json ins Statusverzeichnis, und jeder Befehl greift darauf zu. Sieh Konfiguration dafür, wo dieses Verzeichnis auf jeder Plattform liegt.

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

Die Regeln, die jede Zeile erfüllen muss

• name ist ein Großbuchstaben Identifikator mit bis zu 32 Zeichen, der mit einem Buchstaben beginnt.
• used_percent ist eine Zahl von 0 bis 100.
• reset_at ist ein ISO Zeitpunkt in der Zukunft.
• Bis zu zehn Meter werden gelesen. Zeilen nach der zehnten werden ignoriert.
• Eine Zeile, die eine dieser Regeln bricht, wird verworfen, und die übrigen Zeilen zählen weiter. Nichts wird repariert.

Führ openlimiter snapshot --refresh aus, um die Datei in den Cache einzufalten.

3. Der generische ingest Befehl

Jedes Skript oder jeder Agent kann OpenLimiter ein Dokument übergeben, ohne eine Provider Integration. Der Befehl liest die Standardeingabe, oder ein Inline Dokument, das mit --payload übergeben wird.

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"}]}'

Ohne Provider Flag wird das Dokument als manuelles Dokument behandelt, der entstehende Snapshot trägt also die Präzision von manual. Mit --provider <id> geht das Dokument an den eigenen Parser dieses Connectors und behält dessen Labels.

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

Gültige Provider ids sind claude, openrouter, codex, antigravity, opencode, und manual. Eine unbekannte id ist ein Usage Fehler und beendet sich mit 2.

Was mit den Daten passiert

Eingelesene Zeilen fließen unter demselben Lock, den jeder andere Writer nutzt, in einen Cache zusammen, sodass nichts bereits Gecachtes verloren geht und zwei Writer, die verschiedene Provider beobachten, sich nicht gegenseitig still die Zeilen wegnehmen können.

• Werte werden gegen das Snapshot Schema validiert, bevor irgendetwas geschrieben wird.
• Prozentwerte bleiben zwischen 0 und 100. Ein Wert außerhalb dieses Bereichs wird nicht begrenzt, er wird verworfen.
• Jeder Schreibvorgang läuft über einen atomaren Austausch, ein Leser sieht also entweder den vorherigen oder den neuen Inhalt, nie eine unvollständige Datei.
• Aktualität wird davon abgeleitet, wann ein Wert beobachtet wurde und wann er abläuft, veraltete Daten werden also gekennzeichnet, statt still als aktuell wiederverwendet zu werden.

Übersteht nichts die Validierung? Der Befehl meldet, dass kein begrenzter Meter übrig blieb, und beendet sich mit einem Fehler, statt einen Platzhalter zu schreiben.