Kairos

Track usage and pause prompts ​

Claude Code enforces a five-hour usage limit without advance warning. A task can stop when the limit is reached, with the failure message as the first notice.

Kairos tracks usage within the window, predicts the next turn's cost and pauses prompts before the predicted turn exceeds the estimated limit. The prompt interface offers three options: wait for the window to reset, send anyway or discard the prompt. The prompt remains saved, and /kairos go sends it within the same turn without requiring you to type it again.

Neither usage nor the limit is available as a local record. Kairos reconstructs both from the transcripts Claude Code already writes.

Getting started ​

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

Hooks bind at session start, so start a new session after installation. An existing session will not load the hooks. Kairos requires bash and jq. If jq is missing, the plugin displays one notice and remains inactive.

Measurements and estimates ​

Consumption is reconstructed exactly from the available transcripts. The ceiling is estimated and reported as a range with supporting records. One recorded refusal gives a wide range; three give a narrower range.

An account without a recorded limit refusal has no ceiling range and no prompt gating. Usage is still measured and reported. Gating starts only after a refusal is recorded for that account.

An earlier version used a provisional range based on observed data. Reconstructing every window in that history revealed windows with 16.5M billable tokens and no refusal, while the provisional ceiling was 5.7M. These figures described one subscription, not a general limit. Applying that assumed ceiling to a larger plan would cause repeated unnecessary interruptions.

Kairos reads only the transcripts under ~/.claude/projects. Turns on the same subscription in the desktop app or browser use the same five-hour window but leave no local transcript. If you use more than one interface, treat reported consumption as a lower bound.

Multiple subscriptions ​

Records are separated by account. Usage follows the account charged for each turn, including switches within a session. Max 5x and Max 20x are distinguished because their ceilings differ by roughly a factor of four.

Account attribution comes from each transcript line, not the account logged in when the file is read. A session with an account switch is split at that point. Subagent transcripts contain no owner and make up most files on disk, so a separate hook records the paying account when those transcripts are written.

Refusals require stricter attribution because they are the basis for prompt gating. On a machine with multiple subscriptions, an unattributed refusal is stored and reported but never used for calibration. Older limit records from before account separation cannot be attributed retrospectively and are set aside once on such machines. kairos calibrate rereads the transcripts to assign those refusals to the accounts that incurred them.

A new account starts without calibration records. Estimates improve as records accumulate.

Calculations ​

Consumption includes input tokens, cache creation and output. Cache reads are excluded based on measurements: zero weighting fits the recorded refusals, while including cache reads at any weight makes the error four times larger. Counting cache reads would make the usage measurement wrong by roughly a factor of a hundred.

Five-hour windows are reconstructed from transcript timestamps as chained blocks, rounded down to ten minutes. This model reproduces the reset times in Claude's refusal messages to the minute.

The next-turn estimate uses the 75th percentile of recent turns to account for larger turns. Prompt gating compares this estimate against the optimistic edge of the ceiling range, so prompts are paused only when predicted usage approaches the upper end of the range. This reduces unnecessary interruptions but permits the first limit refusal to occur before gating is calibrated.

Data handling and failure behaviour ​

Kairos never writes account email addresses to disk or runs /login. The report indicates when another account appears to have capacity; you decide whether to switch.

An internal error never blocks a prompt. Every uncertain path allows submission, so a failed measurement does not stop your work.

Troubleshooting ​

Run /kairos to inspect the current measurements. The report distinguishes three states that otherwise produce no visible activity.

Nothing recorded for this account yet means no consumption has been read. Either jq is missing or the session was already running at installation and the hooks are not bound. Start a new session and check again.

No ceiling recorded yet is the normal state before the first limit refusal recorded for an account. kairos calibrate scans the complete transcript history for previously unrecorded refusals and is useful once after installation.

A figure that looks wrong can be compared with kairos accounts. With multiple plans, the main report shows the currently active account; the other accounts are listed separately.

Hooks and storage ​

Five hooks run in the harness without adding model context.

Consumption is read incrementally. A cursor for each transcript records how many bytes have been counted, so a refresh reads only appended data. Cursors are shared across accounts to count each transcript's bytes once. Results are separated by account under ~/.claude/kairos/accounts/, alongside refusal records and turn history.

Platform notes ​

Every push is tested on Linux, macOS and Windows. Tests also run under bash 3.2 on macOS, the version shipped as /bin/bash.

Two earlier defects occurred only on Windows. Git's line-ending conversion could leave a carriage return in a numeric field and cause an arithmetic error. Non-atomic file replacement could also let a concurrent writer remove a file between the existence check and the read. Both defects were found by CI and are handled.

Requirements ​

bash and jq on Linux, macOS or Windows. The test suite runs on all three platforms.