cozempic-doctor

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:

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