cozempic

Cozempic

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

What It Does

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

Key Features

• 18 pruning strategies — gentle (5), standard (11), aggressive (18)
• Guard daemon — auto-starts via SessionStart hook, monitors and prunes continuously
• Interactive "prune now?" nudge — a non-blocking heads-up at 25% / 55% / 80% context (once per tier) recommending cozempic reload, so interactive users get cozempic's higher-fidelity prune+resume on their own terms instead of falling back to lossy autocompact. Takes no action on its own; silence with COZEMPIC_NUDGE_OFF=1
• Interactive-safe reload — in interactive sessions the guard warns first and reloads only at an idle breakpoint (never mid-turn); headless sessions reload as before
• Safe-point protection — the guard never terminates-and-resumes through in-flight work: a running Workflow, a background subagent, an agent team, or an open tool call defers the reload so nothing is lost
• 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
• 15 doctor checks — diagnose and auto-fix session corruption, orphaned tool results, zombie teams, unresumable sessions
• Token-aware diagnostics — exact token counts from usage fields, cache hit rate, context % bar
• Auto-detects 1M context — correct thresholds for both 200K and 1M models
• Efficient idle polling — backs off the poll cadence when the session is quiet and skips redundant no-op checkpoints
• Auto-updates — checks PyPI daily, upgrades in-place

Zero external dependencies. Python 3.10+ stdlib only.

Install

Pick your package manager. uvx/pipx/npm/pip are the lowest-friction (no Homebrew trust prompt — see the note below):

# uv — persistent install, always on PATH (recommended)
uv tool install cozempic

# uvx — run once without installing (handy to try it, but the guard daemon
# can't auto-start from an ephemeral env — use `uv tool install` for that)
uvx cozempic --help

# pipx — isolated user install, always on PATH
pipx install cozempic

# npm — global install
npm install -g cozempic

# pip (Python ≥ 3.10)
pip install cozempic

# Homebrew (macOS / Linux) — use the fully-qualified name (see note below)
brew install Ruya-AI/cozempic/cozempic

# Nix flake
nix profile install github:Ruya-AI/cozempic?dir=packaging/nix

Homebrew tap trust: recent Homebrew versions gate non-official taps behind an explicit trust step. The fully-qualified brew install Ruya-AI/cozempic/cozempic above trusts just this formula inline — no extra command. A bare brew install cozempic / brew upgrade cozempic will instead error with "Refusing to load formula … from untrusted tap"; if you hit that, run brew trust Ruya-AI/cozempic once (or just prefer one of the install methods above, none of which have this gate).

AUR (yay -S cozempic) and MacPorts (port install py-cozempic) submissions are in progress — see packaging/README.md for status and PKGBUILD/Portfile sources.

That's it. Cozempic auto-initializes on first use — hooks are wired globally, guard daemon auto-starts on every Claude Code session. No manual setup needed. Opt out with COZEMPIC_NO_GLOBAL_INIT=1.

Auto-update & how to control it

Cozempic auto-updates from PyPI by default, on purpose: Claude Code ships frequent changes to its session/context format, and auto-update is how a compatibility fix reaches you before a stale release can mishandle and lose your context. For most users that safety outweighs the convenience cost, so we recommend leaving it on. If you'd rather control it, set one of these — ideally in your shell profile (~/.zshrc / ~/.bashrc) so it applies before the first session wires anything:

Goal	Set
Hold a specific reviewed version, keep hooks + guard running	export COZEMPIC_PIN=1.8.30
Stop all auto-updates, keep hooks + guard running	export COZEMPIC_NO_AUTO_UPDATE=1
No global hooks / no daemon at all (manual CLI only)	export COZEMPIC_NO_GLOBAL_INIT=1

Both COZEMPIC_NO_AUTO_UPDATE and COZEMPIC_PIN are honored by the Python updater, the SessionStart hook's shell upgrade, and the npm installer. COZEMPIC_PIN disables auto-update and warns (not auto-installs) if your running version drifts from the pin, so you stay on a version you've reviewed with a human in the loop. (Releases are published from CI via PyPI Trusted Publishing — no long-lived upload token — to reduce the chance of a compromised publish in the first place.)

As a Claude Code Plugin

Install cozempic (any method above), 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 (interactive: at a breakpoint; deferred if agents active)
Hard2	80%	aggressive prune	Yes (gated by the safe-point check)
User	90%	manual aggressive	Yes

Interactive sessions — instead of a surprise reload mid-work, the guard surfaces a nudge and reloads only once you pause between turns, after warning you. Near the wall (≈88%) it reloads even mid-turn — a higher-fidelity prune beats hitting autocompact. Detection is automatic (COZEMPIC_INTERACTIVE=auto); on/off force it. Headless/CI sessions reload immediately as before.

Safe-point reload — a reload terminates and resumes the Claude process, so the guard validates first: if a Workflow, a background subagent, an agent team, or an open tool call is in flight, the reload defers (read-only checkpoint) rather than destroying that work. Tune the near-wall force point with COZEMPIC_FORCE_RELOAD_PCT (default 0.88).

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")
• All corrections start as "pending" and activate after 2 occurrences (prevents one-shot noise from polluting the digest)
• 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