Guard actually works now
The guard daemon has been fundamentally broken since it shipped: it never registered the pruning strategies, so every single prune cycle freed 0 bytes. Combined with a bug that kept creating backups even on failed prunes, users hit 130GB of .jsonl.bak files from stale guard daemons running for days.
This release fixes all of it.
Critical fixes
The 0-bytes prune bug (#15) — guard.py never imported cozempic.strategies, so STRATEGIES was always empty and every strategy was silently skipped. One line fix. Before: 0 bytes freed every cycle. After: 13–37% freed per cycle.
Backup accumulation / disk fill (#16, #19) — guard was creating a new .jsonl.bak on every prune cycle, even failed ones. A stale guard running 69 hours produced 2,843 files totalling 130GB. Fixed: skip save entirely when pruning frees nothing; cap .bak retention at 3 files.
Stale session after restart (#11) — when Claude restarts with a new session, the guard kept watching the old session forever. Fixed: _session_file tracks which session the guard is watching; on mismatch, the stale guard is SIGTERMed and a fresh one starts automatically.
Guard log always empty (#14) — Python buffers stdout when writing to a file, so the log was empty until the process exited (which for a guard daemon, means never). Fixed: PYTHONUNBUFFERED=1 in the daemon subprocess env.
Global flags after subcommand silently rejected (#13) — --context-window and --system-overhead-tokens had to come before the subcommand name or argparse would ignore them. Fixed: _prescan_argv extracts them from any position.
New behaviour
- Token thresholds are automatic — guard now defaults to 75% (hard) / 45% (soft) of the detected context window. No
--threshold-tokensflag needed. - Configurable system overhead —
--system-overhead-tokensflag andCOZEMPIC_SYSTEM_OVERHEAD_TOKENSenv var. Heavy configs (many rules files, MCP servers, large CLAUDE.md) can have 34K+ tokens of overhead vs the 21K default, causing the guard to fire too late. - Circuit breaker — 3 consecutive empty hard prunes triggers a warning and 4× backoff instead of hammering forever.
Credits
Huge thanks to @conal for PR #10 (merged), PRs #12 + #17 (incorporated), and issues #8, #9, #11, #13, #14, #15, #16 — basically a full audit of the guard. And @jacobcxdev for issue #19 (the 130GB disk fill report). This release is largely their work.