Zero external dependencies. Python 3.10+ stdlib only.

Install

pip install cozempic
cozempic init

That's it. The guard daemon auto-starts on every session via hooks. No second terminal needed.

As a Claude Code Plugin

pip install cozempic

Then 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.

Quick Start

# 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

Strategies

| # | 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% |

Prescriptions

| 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.

Guard — Continuous Protection

The guard daemon monitors your session and prunes automatically:

# Auto-starts via SessionStart hook after cozempic init
# Or run manually:
cozempic guard --daemon

4-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.

Behavioral Digest

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 inject

How 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

Agent Teams Protection

When Claude's auto-compaction fires, Agent Teams lose coordination state. Cozempic prevents this with five layers:

1. Continuous checkpoint — saves team state every N seconds
2. Hook-driven checkpoint — fires after every Task spawn, TaskCreate/Update, before compaction, at session end
3. Tiered pruning — soft threshold trims without disruption; hard threshold does full prune + reload
4. Reactive overflow recovery — detects inbox-flood within milliseconds, auto-recovers (~10s downtime)
5. is_protected() — compact summaries, compact boundaries, content-replacement entries, and behavioral digest messages are never stripped

Doctor

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 | — |

Commands

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

Hook Integration

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 |

Safety

• Dry-run by default — --execute required 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.bak before any modification
• is_protected()