Watchdog for AI CLI agent sessions (Claude Code, Codex CLI, Gemini CLI, any JSONL tool transcript).
What's inside
- LOOP detection — same tool+args repeated N times in a sliding window (--loop-n/--loop-m)
- OSCILLATION detection — A→B→A→B edit/revert cycles, window tunable via --osc-n
- STALL detection — no new events for S seconds (--stall-s)
- loopguard replay — annotated event-by-event verdicts; debug thresholds on your own transcripts
- Telegram alerts — LOOPGUARD_TG_TOKEN + LOOPGUARD_TG_CHAT_ID env vars, one alert per incident
- Multi-block parsing — extracts every tool_use block per line (real Claude Code batching)
- Zero dependencies — stdlib-only single file; curl-installable to ~/.local/bin
Install
curl -fsSL https://raw.githubusercontent.com/ruslanlap/loopguard/main/loopguard.py -o ~/.local/bin/loopguard && chmod +x ~/.local/bin/loopguard41 tests, CI matrix: Linux/macOS/Windows × Python 3.10/3.13.