20,000+ power users trust Cozempic to keep their Claude Code sessions lean.
Context cleaning for Claude Code ��� remove the bloat, keep everything that matters, protect Agent Teams from context loss.
Claude Code sessions fill up with dead weight: progress ticks, thinking blocks, stale file reads, duplicate CLAUDE.md injections, base64 screenshots, oversized tool outputs, and metadata bloat. A typical session carries 8-46MB — most of it noise that inflates every API call.
Cozempic removes it with 17 composable strategies across 3 prescription tiers, while your actual conversation, decisions, and working context stay untouched. The guard daemon runs automatically — install once, forget about it.
- 18 pruning strategies — gentle (5), standard (11), aggressive (18)
- Guard daemon — auto-starts via SessionStart hook, monitors and prunes continuously
- compact-summary-collapse — 85-95% savings by removing pre-compaction messages already in the summary
- Agent Teams protection — checkpoints team state through compaction, reactive overflow recovery
- Behavioral digest — extracts your corrections ("don't do X"), persists them to Claude Code's memory system so they survive compaction
- 8 doctor checks — diagnose and auto-fix session corruption, orphaned tool results, zombie teams
- Token-aware diagnostics — exact token counts from
usagefields, cache hit rate, context % bar - Auto-detects 1M context — correct thresholds for both 200K and 1M models
- Auto-updates — checks PyPI daily, upgrades in-place
Zero external dependencies. Python 3.10+ stdlib only.
pip install cozempic
cozempic initThat's it. The guard daemon auto-starts on every session via hooks. No second terminal needed.
pip install cozempicThen inside Claude Code:
/plugin marketplace add Ruya-AI/cozempic
/plugin install cozempic
This gives you MCP tools, skills (/cozempic:diagnose, /cozempic:treat, etc.), and auto-wired hooks.
# Auto-detect and diagnose the current session
cozempic current --diagnose
# Dry-run the standard prescription
cozempic treat current
# Apply with backup
cozempic treat current --execute
# Go aggressive on a specific session
cozempic treat <session_id> -rx aggressive --execute
# Check for session corruption
cozempic doctor
# View behavioral digest rules
cozempic digest show
# Show all strategies & prescriptions
cozempic formulary| # | Strategy | Tier | What It Does | Expected |
|---|---|---|---|---|
| 1 | compact-summary-collapse |
gentle | Remove all pre-compaction messages (already in the summary) | 85-95% |
| 2 | attribution-snapshot-strip |
gentle | Strip attribution-snapshot metadata entries | 0-2% |
| 3 | progress-collapse |
gentle | Collapse consecutive and isolated progress tick messages | 40-48% |
| 4 | file-history-dedup |
gentle | Deduplicate file-history-snapshot messages | 3-6% |
| 5 | metadata-strip |
gentle | Strip token usage stats, stop_reason, costs | 1-3% |
| 6 | thinking-blocks |
standard | Remove/truncate thinking content + signatures | 2-5% |
| 7 | tool-output-trim |
standard | Trim large tool results (>8KB or >100 lines), microcompact-aware | 1-8% |
| 8 | tool-result-age |
standard | Compact old tool results by age — minify mid-age, stub old | 10-40% |
| 9 | stale-reads |
standard | Remove file reads superseded by later edits | 0.5-2% |
| 10 | system-reminder-dedup |
standard | Deduplicate repeated system-reminder tags | 0.1-3% |
| 11 | tool-use-result-strip |
standard | Strip toolUseResult envelope field (Edit diffs, never sent to API) | 5-50% |
| 12 | image-strip |
aggressive | Strip old base64 image blocks, keep most recent 20% | 1-40% |
| 13 | http-spam |
aggressive | Collapse consecutive HTTP request runs | 0-2% |
| 14 | error-retry-collapse |
aggressive | Collapse repeated error-retry sequences | 0-5% |
| 15 | background-poll-collapse |
aggressive | Collapse repeated polling messages | 0-1% |
| 16 | document-dedup |
aggressive | Deduplicate large document blocks (CLAUDE.md injection) | 0-44% |
| 17 | mega-block-trim |
aggressive | Trim any content block over 32KB | safety net |
| 18 | envelope-strip |
aggressive | Strip constant envelope fields (cwd, version, slug) | 2-4% |
| Prescription | Strategies | Risk | Typical Savings |
|---|---|---|---|
gentle |
5 | Minimal | 85-95% (with compact boundary) |
standard |
11 | Low | 25-45% |
aggressive |
18 | Moderate | 35-60% |
Dry-run is the default. Nothing is modified until you pass --execute. Backups are always created.
The guard daemon monitors your session and prunes automatically:
# Auto-starts via SessionStart hook after cozempic init
# Or run manually:
cozempic guard --daemon4-tier proactive pruning (every 30s):
| Tier | Threshold | Action | Reload? |
|---|---|---|---|
| Soft | 25% | gentle file cleanup | No |
| Hard | 55% | standard prune | Yes (deferred if agents active) |
| Emergency | 80% | aggressive prune | Yes (forced) |
| User | 90% | manual aggressive | Yes |
Reactive overflow recovery — kqueue/polling file watcher detects inbox-flood overflow within milliseconds, auto-prunes with escalating prescriptions, circuit breaker prevents loops.
tmux/screen — reload resumes in the same pane via send-keys. Plain terminals open a new window.
Token thresholds auto-detect — 200K and 1M models detected automatically. Override with COZEMPIC_CONTEXT_WINDOW=200000 for Pro plan.
Cozempic extracts your corrections and persists them across compactions:
# View extracted rules
cozempic digest show
# Manually extract from current session
cozempic digest update
# Sync rules to Claude Code's memory system
cozempic digest injectHow it works:
- Detects correction signals in your messages ("don't do X", "stop adding Y", "always use Z")
- Explicit corrections activate immediately; implicit corrections need 2 occurrences
- Rules synced to Claude Code's native memory system (
~/.claude/projects/<cwd>/memory/) - Claude reads these as feedback memories on every turn — they survive compaction natively
- PreCompact and Stop hooks auto-extract before context is lost
When Claude's auto-compaction fires, Agent Teams lose coordination state. Cozempic prevents this with five layers:
- Continuous checkpoint — saves team state every N seconds
- Hook-driven checkpoint — fires after every Task spawn, TaskCreate/Update, before compaction, at session end
- Tiered pruning — soft threshold trims without disruption; hard threshold does full prune + reload
- Reactive overflow recovery — detects inbox-flood within milliseconds, auto-recovers (~10s downtime)
- is_protected() — compact summaries, compact boundaries, content-replacement entries, and behavioral digest messages are never stripped
cozempic doctor # Diagnose issues
cozempic doctor --fix # Auto-fix where possible| Check | What It Detects | Auto-Fix |
|---|---|---|
trust-dialog-hang |
Resume hangs on Windows | Reset flag |
claude-json-corruption |
Truncated/corrupted JSON | Restore from backup |
corrupted-tool-use |
tool_use.name >200 chars |
Parse and repair |
orphaned-tool-results |
tool_result missing matching tool_use — causes 400 errors |
Strip orphans |
zombie-teams |
Stale team directories with dead agents | Remove stale dirs |
oversized-sessions |
Session files >50MB | — |
stale-backups |
Old .jsonl.bak files wasting disk |
Delete old backups |
disk-usage |
Session storage exceeding healthy thresholds | — |
cozempic init Wire hooks + slash command into project
cozempic list List sessions with sizes and token estimates
cozempic current [-d] Show/diagnose current session
cozempic diagnose <session> Analyze bloat sources
cozempic treat <session> [-rx PRESET] Run prescription (dry-run default)
cozempic treat <session> --execute Apply changes with backup
cozempic strategy <name> <session> Run single strategy
cozempic reload [-rx PRESET] Treat + auto-resume in new terminal
cozempic checkpoint [--show] Save team state to disk
cozempic guard [--daemon] Start guard (auto-starts via hook)
cozempic doctor [--fix] Check for known issues
cozempic digest [show|update|clear|flush|recover|inject]
cozempic self-update Upgrade to latest version from PyPI
cozempic formulary Show all strategies & prescriptions
After cozempic init, these hooks are wired automatically:
| Hook | When | What |
|---|---|---|
SessionStart |
Session opens | Guard daemon + digest inject |
PostToolUse[Task] |
Agent spawn | Team checkpoint |
PostToolUse[TaskCreate|TaskUpdate] |
Todo changes | Team checkpoint |
PreCompact |
Before compaction | Checkpoint + digest flush |
Stop |
Session end | Checkpoint + digest flush |
- Dry-run by default —
--executerequired to modify files - Atomic writes —
write → fsync → os.replace()— no partial writes - Strict session resolution — refuses to act on ambiguous matches
- Timestamped backups — automatic
.jsonl.bakbefore any modification - is_protected() — compact summaries, boundaries, marble-origami state, content-replacement, behavioral digest entries are never removed
- parentUuid re-linking — conversation chain integrity maintained after removals
- Sibling tool_use protection — tool_use blocks are kept when their tool_result is kept
- Team messages protected — Task, TaskCreate, SendMessage never pruned
- Strategies compose sequentially — each runs on the output of the previous
Prescription: aggressive
Before: 158.2K tokens (29.56MB, 6602 messages)
After: 121.5K tokens (23.09MB, 5073 messages)
Freed: 36.7K tokens (23.2%) — 6.47MB, 1529 removed, 4038 modified
Context: [============--------] 61%
Strategy Results:
compact-summary-collapse 8.17MB saved (85.2%) (4201 removed)
progress-collapse 1.63MB saved (5.5%) (1525 removed)
metadata-strip 693.9KB saved (2.3%) (2735 modified)
tool-use-result-strip 1.44MB saved (4.9%) (891 modified)
thinking-blocks 1.11MB saved (3.8%) (1127 modified)
tool-output-trim 1.72MB saved (5.8%) (167 modified)
...
- 4-tier pruning: soft (25%, no reload) → hard (55%, reload) → emergency (80%, aggressive reload) → user (90%, manual)
- Agent-aware reload: defers reload at 55% when agents are running, forces at 80%
- Same-terminal resume: tmux/screen users get
/exit+claude --resumein the same pane - Clean messaging: only shows strategies that did something, 1-line hook status output
- 1M default: Opus/Sonnet 4.5/4.6 default to 1M context (CC doesn't use
[1m]suffix) - Auto-upgrade everywhere: SessionStart hook backgrounds
pip install --upgrade cozempicon every session. MCP/plugin useuv run --upgrade. npm install.js always upgrades. cozempic self-update: force-upgrade from PyPI regardless of install method (pip, uv, editable, clone)- Auto-updater fixed: removed TTY check (was blocking hook-triggered updates), tries uv → pip → pipx
tool-result-agestrategy — age-based tool result compaction. Recent results stay verbatim, mid-age get JSON minified and diff context collapsed, old replaced with compact stubs. Claude can re-read any file. 10-40% additional savings targeting the 45% of session size that tool results occupy.- 18 strategies total, standard prescription 11, aggressive 18
- Tests: 273 → 283
- Track 1 — Bug fixes:
is_protected()guard on all strategies,isSidechainpreserved in envelope-strip,output_tokensin token formula,parentUuidre-linking, sibling tool_use protection - Track 2 — New strategies:
compact-summary-collapse(85-95%),attribution-snapshot-strip, microcompact-awaretool-output-trim - Behavioral digest: extract corrections, sync to Claude Code memory, CLI commands, hook wiring
- Context window detection: MCP server and plugin now auto-detect 200K/1M (was hardcoded 200K)
- Cache efficiency metrics:
cozempic diagnoseshows cache hit rate - transcript_path: hooks parse session path from payload for faster resolution
- Tests: 165 → 273
- Writer-safe live prune + sidecar session store
- Guard startup cleanup, updater fixes, MCP maintenance
- Atomic file writes, strict session resolution, schema-first team detection
- tool-use-result-strip strategy (5-50% on edit-heavy sessions)
- image-strip strategy (keep last 20%)
- Auto-update, install tracking, npm package
- Safety improvements: SIGTERM handler, backup cleanup, permission error handling
Contributions welcome. To add a strategy:
- Create a function in the appropriate tier file under
src/cozempic/strategies/ - Decorate with
@strategy(name, description, tier, expected_savings) - Return a
StrategyResultwith a list ofPruneActions - Add to the appropriate prescription in
src/cozempic/registry.py
MIT — see LICENSE.
Built by Ruya AI.