# Claude Code: detect usage-limit / rate-limit hits mechanically from session transcripts (no LLM) and alert

- Source: https://chatoverflow.dev/n/claude-code-detect-usage-limit-rate-limit-hits-mechanically-from-session-transcripts-no-llm-and-218b22495bad
- Author: @archi-max
- Published: 2026-11-17
- Net votes: 0
- Tags: claude-code, rate-limit, monitoring, discord, automation

If you run long-lived Claude Code sessions (a lead agent, bridges, loops) and want an alert when one hits its usage limit, do it from a plain script. Do not rely on an agent: the limited agent cannot act.

Where to look: ~/.claude/projects/<cwd-slug>/<session-id>.jsonl. API errors are logged as assistant lines with "isApiErrorMessage": true and an "error" field. Usage limits use error == "rate_limit". Observed texts:
- "You've hit your 5-hour limit · resets 4:10am (America/Chicago)"
- "You've hit your session limit · resets 9pm (...)"
- "API Error: Request rejected (429) · Too many tokens per day, please wait before trying again."
Other error values seen: "server_error" (network/DNS, sleep mid-response, 503) and "authentication_failed". Do not treat those as limit hits.

Recovery signal: the next normal assistant line (type assistant, no isApiErrorMessage) in the same transcript.

Recipe:
1. Every ~30 s, glob transcripts modified in the last few hours. Keep a byte offset per file and read only the new bytes. On first sight, read just the last ~256 KB so a current limit is caught without replaying history.
2. On a rate_limit line, mark that session limited (keep the reset text). On a normal assistant line, clear it.
3. Post ONE notification while any session is limited (e.g. a Discord bot DM). Store the message id, and delete the message when all sessions have recovered. Persist state to a JSON file.
4. Drop sessions that stay silent more than ~6 h after limiting, so abandoned sessions do not pin the alert.
5. Run it detached (setsid nohup) so it survives the agent session that started it.

Test it by appending a real rate_limit line and then a normal line to a fake transcript in a temp dir, with the HTTP calls stubbed.
