Kairos

Volg het verbruik en pauzeer prompts ​

Claude Code hanteert een gebruikslimiet van vijf uur zonder voorafgaande waarschuwing. Een taak kan stoppen zodra de limiet is bereikt, met de foutmelding als eerste signaal.

Kairos houdt het verbruik binnen het venster bij, voorspelt de kosten van de volgende beurt en pauzeert prompts voordat die beurt de geschatte limiet overschrijdt. De promptinterface biedt drie opties: wachten tot het venster reset, toch versturen of de prompt laten vallen. De prompt blijft bewaard. Met /kairos go verstuur je de prompt binnen dezelfde beurt zonder opnieuw te typen.

Noch het verbruik, noch de limiet is als lokaal record beschikbaar. Kairos reconstrueert beide uit de transcripties die Claude Code al wegschrijft.

Aan de slag ​

claude plugin marketplace add https://github.com/AraneaDev/aranea-marketplace
claude plugin install kairos@aranea

Hooks worden bij het begin van een sessie gebonden. Start daarom na installatie een nieuwe sessie; een bestaande sessie laadt de hooks niet. Kairos vereist bash en jq. Als jq ontbreekt, toont de plugin één melding en blijft de plugin inactief.

Metingen en schattingen ​

Het verbruik wordt exact gereconstrueerd uit de beschikbare transcripties. Het plafond is een schatting en wordt als bereik getoond met de onderliggende records. Eén vastgelegde weigering geeft een breed bereik; drie geven een smaller bereik.

Een account zonder vastgelegde limietweigering krijgt geen plafondbereik en geen promptblokkering. Het verbruik wordt wel gemeten en gerapporteerd. Blokkering begint pas nadat voor dat account een weigering is vastgelegd.

Een eerdere versie gebruikte een voorlopig bereik op basis van waargenomen gegevens. Bij het narekenen van alle vensters in die geschiedenis bleken er vensters met 16,5 miljoen betaalde tokens zonder weigering te zijn, terwijl het voorlopige plafond 5,7 miljoen was. Die getallen beschreven één abonnement, geen algemene limiet. Zo'n aangenomen plafond zou bij een groter abonnement herhaaldelijk onnodige onderbrekingen veroorzaken.

Kairos leest alleen transcripties onder ~/.claude/projects. Beurten op hetzelfde abonnement in de desktop-app of browser gebruiken hetzelfde vijfuursvenster, maar laten geen lokale transcriptie achter. Gebruik je meerdere interfaces, lees het gerapporteerde verbruik dan als ondergrens.

Meerdere abonnementen ​

Records worden per account gescheiden. Verbruik wordt toegewezen aan het account dat voor elke beurt betaalt, ook bij een wissel binnen een sessie. Max 5x en Max 20x worden onderscheiden, omdat de plafonds ongeveer een factor vier verschillen.

De accounttoewijzing komt uit elke transcriptieregel, niet uit het account dat tijdens het lezen is ingelogd. Een sessie met een accountwissel wordt op dat punt gesplitst. Transcripties van subagents bevatten geen eigenaar en vormen het merendeel van de bestanden op schijf. Een aparte hook legt daarom het betalende account vast wanneer deze transcripties worden geschreven.

Weigeringen vereisen strengere toewijzing, omdat deze de basis vormen voor promptblokkering. Op een machine met meerdere abonnementen wordt een weigering zonder zekere accounttoewijzing wel bewaard en gerapporteerd, maar nooit gebruikt voor kalibratie. Oudere limietrecords van vóór de accountscheiding zijn achteraf niet toe te wijzen en worden op zulke machines één keer apart gezet. kairos calibrate leest de transcripties opnieuw om die weigeringen toe te wijzen aan het bijbehorende account.

Een nieuw account begint zonder kalibratierecords. De schattingen verbeteren naarmate meer records beschikbaar komen.

Berekeningen ​

Het verbruik omvat input-tokens, cache-aanmaak en output. Cache-reads zijn uitgesloten op basis van metingen: een gewicht van nul past bij de vastgelegde weigeringen, terwijl ieder gewicht voor cache-reads de fout vier keer zo groot maakt. Bij meetellen zou de verbruiksmeting er ongeveer een factor honderd naast zitten.

Vijfuursvensters worden uit transcriptietimestamps gereconstrueerd als aaneengesloten blokken, naar beneden afgerond op tien minuten. Dit model reproduceert de resettijden uit de weigeringsmeldingen van Claude tot op de minuut.

De schatting van de volgende beurt gebruikt het 75e percentiel van recente beurten om rekening te houden met grotere beurten. Promptblokkering vergelijkt deze schatting met de ruime kant van het plafondbereik. Prompts worden daardoor pas gepauzeerd wanneer ook dat hogere plafond nadert. Dit beperkt onnodige onderbrekingen, maar laat de eerste limietweigering plaatsvinden voordat de blokkering is gekalibreerd.

Gegevensopslag en gedrag bij fouten ​

Kairos schrijft nooit e-mailadressen van accounts naar schijf en voert nooit /login uit. Het rapport geeft aan wanneer een ander account ruimte lijkt te hebben; je bepaalt zelf of je wisselt.

Een interne fout blokkeert nooit een prompt. Elk onzeker pad laat de prompt door, zodat een mislukte meting je werk niet stillegt.

Problemen oplossen ​

Voer /kairos uit om de huidige metingen te bekijken. Het rapport onderscheidt drie toestanden die anders geen zichtbare activiteit opleveren.

Nog niets vastgelegd voor dit account betekent dat er geen verbruik is ingelezen. jq ontbreekt, of de sessie draaide al tijdens de installatie waardoor de hooks niet zijn gebonden. Start een nieuwe sessie en controleer opnieuw.

Nog geen plafond vastgelegd is de normale toestand voordat de eerste limietweigering voor een account is geregistreerd. kairos calibrate doorzoekt de volledige transcriptiegeschiedenis op nog niet vastgelegde weigeringen en is na installatie één keer nuttig.

Een getal dat niet klopt kun je vergelijken met kairos accounts. Bij meerdere abonnementen toont het hoofdrapport het actieve account; de andere accounts staan apart vermeld.

Hooks en opslag ​

Vijf hooks draaien in de harness zonder modelcontext toe te voegen.

Verbruik wordt stapsgewijs ingelezen. Een cursor per transcriptie legt vast hoeveel bytes al geteld zijn, zodat een verversing alleen toegevoegde gegevens leest. Cursors worden over accounts gedeeld om elke byte één keer te tellen. Resultaten staan per account gescheiden onder ~/.claude/kairos/accounts/, naast de weigeringsrecords en beurtgeschiedenis.

Platformnotities ​

Elke push wordt getest op Linux, macOS en Windows. Op macOS draaien de tests ook onder bash 3.2, de versie die als /bin/bash wordt meegeleverd.

Twee eerdere fouten deden zich alleen op Windows voor. De omzetting van regeleindes door git kon een carriage return in een getalsveld achterlaten en zo een rekenfout veroorzaken. Ook kon het niet-atomaire vervangen van een bestand door een gelijktijdige schrijver een bestand laten verdwijnen tussen de bestaanscontrole en het lezen. Beide fouten zijn door CI gevonden en worden afgevangen.

Vereisten ​

bash en jq op Linux, macOS of Windows. De testsuite draait op alle drie de platforms.