Kairos

Wat hij doet ​

Claude Code hanteert een gebruikslimiet van vijf uur en waarschuwt daar niet voor. Het werk valt stil midden in een taak, op een moment dat de limiet kiest in plaats van jij, en het enige teken is de foutmelding zelf.

Kairos houdt bij hoeveel van het venster je hebt uitgegeven, voorspelt wat je volgende beurt gaat kosten, en weigert de prompt voordat die beurt je door de muur heen duwt. Word je tegengehouden, dan vraagt Kairos wat je wilt: wachten tot het venster reset, toch versturen of laten vallen. De prompt zelf blijft bewaard, en met /kairos go verstuur je hem alsnog, binnen dezelfde beurt. Je hoeft hem niet opnieuw te typen.

Nergens op je machine staat hoeveel van de limiet je hebt verbruikt, of waar de limiet ligt. Allebei worden ze gereconstrueerd uit de transcripten die Claude Code toch al wegschrijft.

Aan de slag ​

claude plugin marketplace add https://aranea-development.nl/plugins/marketplace.json
claude plugin install kairos@aranea

Hooks worden bij de start van een sessie gebonden, dus begin een nieuwe sessie voordat Kairos iets doet. Een sessie die al draait, pikt ze niet meer op. Je hebt bash en jq nodig, en ontbreekt jq, dan zegt Kairos dat één keer en doet verder niets.

Loopt de installatie vast op ssh: connect to host github.com port 22, dan haalt git de plugin uit de GitHub-repository over SSH en lukt dat op die machine niet. De melding wijst op toegangsrechten, maar de repository is openbaar. Het transport is het probleem. Eén regel zet git op HTTPS, daarna kun je opnieuw installeren:

git config --global --add url."https://github.com/".insteadOf "git@github.com:"

In de README staat de uitgebreide versie, inclusief hoe je het terugdraait.

Wat hij weet, en wat niet ​

Het verbruik reconstrueert Kairos exact, het plafond bij benadering. Daarom wordt het plafond gerapporteerd als een bereik, met het bewijs waarop het berust. Eén vastgelegde weigering geeft een breed bereik, drie geven een smaller.

Een account waarvan Kairos nooit een weigering heeft gezien, krijgt helemaal geen bereik en wordt nooit tegengehouden. Hij meet, hij rapporteert, en hij blijft uit de weg tot hij een muur van dat account zelf heeft waargenomen.

Dat is een keuze, geen omissie. Een eerdere versie vulde een aannemelijk bereik alvast in op basis van waargenomen data. Toen elk venster in diezelfde geschiedenis werd nagerekend, bleken er vensters van 16,5 miljoen tokens te zijn zonder ook maar één weigering, terwijl die aanname bij 5,7 miljoen ophield. Die getallen golden voor één abonnement en zeiden niets over de vorm van de limiet. Een geraden plafond zou je op een groter abonnement voortdurend onderbreken en ondertussen doen alsof het iets wist dat het nooit had gezien.

Eén ding blijft sowieso buiten beeld. Kairos leest alleen wat Claude Code naar ~/.claude/projects schrijft. Beurten die je op hetzelfde abonnement in de desktop-app of in de browser doet, komen uit datzelfde venster van vijf uur en laten op je schijf niets achter. Werk je op meer dan één plek, lees het rapport dan als een ondergrens.

Twee abonnementen ​

Heb je meer dan één Claude-abonnement en wissel je ertussen, dan houdt Kairos ze uit elkaar. Alles wat hij vastlegt is per account gescheiden, en een sessie volgt het account dat daadwerkelijk betaalt, ook als je halverwege wisselt. Een Max 5x wordt onderscheiden van een Max 20x, want hun plafonds schelen ongeveer een factor vier en dat onderscheid is nu juist het punt.

Welk account een beurt betaalt, leest Kairos uit het transcript zelf, en niet uit het account waarop op dat moment is ingelogd. Claude Code schrijft de eigenaar regel voor regel mee, dus een sessie die halverwege van hand wisselt, wordt ook halverwege gesplitst. Transcripten van subagents noemen geen eigenaar, en zij vormen het merendeel van de bestanden op schijf, dus daarvoor legt een aparte hook vast welk account betaalde toen ze geschreven werden.

Een weigering wordt strenger behandeld dan een beurt, want een weigering is het enige dat Kairos toestemming geeft je te onderbreken. Op een machine met meer dan één abonnement wordt een weigering die niet met zekerheid bij een account te plaatsen is, wel bewaard en gerapporteerd, maar nooit gebruikt om te ijken. Muren die zijn vastgelegd voordat Kairos dit onderscheid maakte, vallen achteraf niet meer uit elkaar te houden en worden op zo'n machine één keer opzijgezet. kairos calibrate leest ze opnieuw uit de transcripten, ditmaal op het account dat ze opliep.

Kairos begint bij een nieuw account met niets en wordt beter naarmate hij draait.

Hoe de getallen tot stand komen ​

Verbruik telt input-tokens, cache-aanmaak en output. Cache-reads tellen niet mee, en dat is gemeten. Ze op nul wegen past bij de vastgelegde weigeringen; laat je ze meetellen, dan wordt de fout bij elk gewicht vier keer zo groot. Een meter die ze meetelde, zat er ongeveer een factor honderd naast.

De vijfuursvensters worden uit de timestamps in de transcripten gereconstrueerd als aaneengesloten blokken, afgerond op tien minuten. Dat model reproduceert de reset-tijden die Claude in zijn eigen weigeringen noemt, tot op de minuut.

De volgende beurt wordt voorspeld met het 75e percentiel van de recente beurten, omdat het juist de uitschieters zijn die een sessie door een limiet heen duwen. Kairos rekent tegen de ruime kant van het bereik en blijft dus stil tot zelfs een royaal plafond in zicht komt. Liever laat Kairos je een eerste keer tegen de muur lopen dan dat hij je een maand lang ten onrechte stoort.

Wat hij nooit doet ​

Hij legt je e-mailadres nooit op schijf vast. Hij voert nooit zelf /login uit; hij zegt wel wanneer een ander account vrij lijkt en laat de keuze aan jou. En hij blokkeert nooit een prompt omdat er iets in Kairos zelf stukging. Elk onzeker pad laat de prompt door: een misrekening in het budget is vervelend, maar een meter die je werk stillegt omdat hij zelf stuk is, is erger dan geen meter.

Als er iets misgaat ​

Voer /kairos uit. Dat toont wat de plugin op dit moment denkt, en dat is meestal genoeg om de drie stille toestanden uit elkaar te houden, want van buitenaf lijken ze op elkaar.

Nog niets vastgelegd voor dit account betekent dat er geen verbruik is ingelezen. Of jq ontbreekt, of de hooks zijn niet gebonden omdat de sessie al liep toen je de plugin installeerde. Begin een nieuwe sessie en kijk opnieuw.

Nog geen plafond vastgelegd is geen fout. Dat is de normale toestand voor een account dat nog nooit tegen een limiet is gelopen terwijl Kairos meekeek, en dat blijft zo totdat het gebeurt. kairos calibrate doorzoekt je hele transcriptgeschiedenis op weigeringen die nog niet zijn gezien, en dat is na het installeren één keer de moeite waard.

Een getal dat niet klopt is het waard om naast kairos accounts te leggen. Gebruik je meer dan één abonnement, dan hoort het getal dat je ziet bij het account dat nu actief is, en staat het andere ernaast.

Hoe hij werkt ​

Vijf hooks, allemaal alleen in de harness, dus niets hiervan kost context van het model.

Verbruik wordt stapsgewijs ingelezen. Een cursor per transcript houdt bij hoeveel bytes al geteld zijn, zodat een verversing alleen leest wat er sindsdien bij kwam. Die cursors staan bij elkaar en niet per account, want de bytes van een transcript horen één keer geteld te worden, hoeveel accounts je ook gebruikt. Wat het oplevert, staat wél per account gescheiden, onder ~/.claude/kairos/accounts/, waar ook de vastgelegde weigeringen en de beurtgeschiedenis staan.

Platformnotities ​

Bij elke push getest op Linux, macOS en Windows, en op macOS bovendien onder bash 3.2, want dat is wat macOS nog steeds als /bin/bash meelevert.

Twee fouten in de geschiedenis van deze plugin deden zich alleen op Windows voor. Git zet regeleindes om bij checkout, en een carriage return die met een getalsveld meelift, levert geen verkeerd getal op maar een rekenfout. En een bestand vervangen gaat daar niet in één ondeelbare stap, dus een gelijktijdige schrijver kan een bestand laten verdwijnen tussen de bestaanscontrole en het lezen. Beide zijn afgevangen, en beide zijn door CI gevonden.

Wat je nodig hebt ​

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