Cozempic: context-cleaning voor Claude Code

Definitie

Cozempic is een Python CLI die Claude Code sessie-files (de .jsonl logs onder ~/.claude/projects/) prunet door dode ballast te verwijderen: progress ticks, thinking blocks, stale file reads, dubbele CLAUDE.md injecties, metadata, base64 screenshots en oversized tool outputs. Het werkt als onderhoudslaag bovenop Claude Code’s eigen auto-compaction en hooks.

Context

Lange Claude Code sessies lopen vol met bloat die nooit meer relevant wordt maar wel in elke API-call meegaat. Een typische sessie groeit door naar 8 tot 46 MB, waarvan het grootste deel ruis is. Dat inflateert tokenkosten en versnelt auto-compaction, wat weer coordinatie-state van Agent Teams breekt. Cozempic lost dit op door gericht te strippen wat niet meer nodig is en Agent Team state door compaction heen te tillen via checkpoints.

Relevant vanaf het moment dat sessies langer duren dan een paar uur of dat meerdere subagents parallel draaien. Niet nodig voor korte, enkele-taakopdrachten.

Kernpunten

Installatie via pipx

Op macOS met Homebrew Python blokkeert PEP 668 een gewone pip install (zie wiki-macos-python-pipx). Werkt wel via:

pipx install cozempic
cozempic init

De init-stap bedraadt hooks in ~/.claude/settings.json en plaatst een /cozempic slash-command in ~/.claude/commands/. Een backup van de bestaande settings komt naast het origineel als settings.YYYYMMDD_HHMMSS.bak.

Drie prescription tiers

Cozempic heeft 18 composable strategieen verdeeld over drie tiers:

• Gentle (5 strategieen): minimale impact, tot 85 a 95% besparing wanneer er al een compact boundary in de sessie zit. Voorbeelden: compact-summary-collapse (verwijdert pre-compaction berichten die al in de summary staan), progress-collapse, metadata-strip, file-history-dedup.
• Standard (11 strategieen): normale onderhoudsloop, 25 a 45% besparing zonder compact boundary. Voegt toe: thinking-blocks, tool-output-trim, tool-result-age, stale-reads, system-reminder-dedup, tool-use-result-strip.
• Aggressive (18 strategieen): 35 a 60% besparing, moderaat risico. Voegt image-strip, http-spam, error-retry-collapse, document-dedup, mega-block-trim, envelope-strip toe.

Dry-run is altijd de default. --execute is vereist om een bestand daadwerkelijk te wijzigen. Een getimestampte .jsonl.bak backup komt automatisch naast het origineel.

Guard daemon met 4-tier proactieve pruning

Na cozempic init start de guard daemon automatisch via een SessionStart hook. Geen tweede terminal nodig. De guard monitort elke 30 seconden en prunet in vier drempels:

Drempel	Actie	Reload
25% context	gentle file cleanup	nee
55% context	standard prune	ja, uitgesteld als agents actief
80% context	aggressive prune	ja, geforceerd
90% context	manual aggressive	ja

Bij tmux of screen herlaadt de guard Claude Code in dezelfde pane via send-keys. Plain terminals krijgen een nieuw venster. Context-vensters (200K of 1M) worden auto-gedetecteerd uit het model.

Reactive overflow recovery

Los van de proactieve tiers monitort een kqueue/polling file watcher op inbox-overflow. Bij detectie volgt automatische pruning binnen milliseconden met escalerende prescription, met een circuit breaker die loops voorkomt. Downtime is ongeveer 10 seconden.

Agent Teams protectie

Claude’s auto-compaction breekt Team coordination state. Cozempic beschermt dit met vijf lagen: continuous checkpointing, hook-driven checkpointing bij Task spawn, tiered pruning die teams respecteert, reactive overflow recovery, en een is_protected() guard die compact summaries, compact boundaries, content-replacement entries en behavioral digest messages nooit strip.

Behavioral digest: persistentie van correcties

Cozempic extraheert correcties uit gebruikersberichten (“niet X doen”, “altijd Y”) en schrijft ze weg naar Claude Code’s native memory systeem onder ~/.claude/projects/<cwd>/memory/. Expliciete correcties activeren direct, impliciete pas na twee voorkomens. Het memory-systeem leest deze als feedback memories elke turn en ze overleven compaction. Regels als “geen em dashes” worden zo automatisch persistent.

Commands: cozempic digest show (regels bekijken), update, inject, flush, recover.

Doctor: sessie-corruptie diagnose en fixes

cozempic doctor controleert 8 bekende problemen: trust-dialog hang op Windows, .claude.json corruptie, corrupted tool_use namen, orphaned tool_results (veroorzaken API 400-fouten), zombie team dirs, oversized sessions groter dan 50 MB, stale .jsonl.bak backups, en disk-usage thresholds. Met --fix worden fixes waar mogelijk automatisch toegepast.

Hook-integratie na init

Init bedraadt deze hooks in ~/.claude/settings.json:

Hook	Trigger	Actie
SessionStart	sessie opent	guard daemon + digest inject
PostToolUse[Task]	agent spawn	team checkpoint
PostToolUse[TaskCreate|TaskUpdate]	todo changes	team checkpoint
PreCompact	voor compaction	checkpoint + digest flush
PostCompact	na compaction	recovery context
Stop	sessie-einde	checkpoint + digest flush

Veiligheid

Atomic writes via write -> fsync -> os.replace(), strict session resolution die ambiguity weigert, timestamped backups, is_protected() guard op alle strategieen, parentUuid re-linking voor conversation chain integrity, sibling tool_use protectie bij pruning, en Task/TaskCreate/SendMessage berichten worden nooit geprund.

Typische cijfers uit praktijkrun

Op een live sessie van 52,7K tokens leverde de standard prescription zonder compact boundary:

• tool-use-result-strip: 26,5 KB (edit diffs uit envelope)
• metadata-strip: 16,1 KB (token counts, stop_reason, kosten)
• tool-output-trim: 9 KB
• thinking-blocks: 6,1 KB
• Totaal: 7,6K tokens bespaard, 57,8 KB (14,5%)

Grote winst komt pas na auto-compaction: compact-summary-collapse levert dan 85 a 95%.

Auto-update

cozempic self-update forceert upgrade vanaf PyPI ongeacht installatiemethode. De SessionStart hook probeert elke sessie een achtergrond upgrade via uv, pip of pipx.

Verbanden

• Zie ook: wiki-macos-python-pipx
• Zie ook: wiki-claude-workspace-setup
• Zie ook: wiki-claude-data-locaties
• Gerelateerd project: cc-setup

Bronnen

• Repository: Ruya-AI/cozempic op GitHub (MIT, Python 3.10+ stdlib only, v1.6.19 bij installatie)
• PyPI: cozempic
• Auteur: Ruya AI / Junaid Qureshi

Sessie-herkomst

• raw-sessie-2026-04-14-cozempic-en-backlog-update