# Cozempic

![Downloads](https://img.shields.io/badge/downloads-20k%2B-brightgreen) ![Version](https://img.shields.io/badge/version-1.6.1-blue) ![License](https://img.shields.io/badge/license-MIT-lightgrey)

**20,000+ power users** trust Cozempic to keep their Claude Code sessions lean.

Context cleaning for [Claude Code](https://claude.ai/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 **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.

### Key Features

- **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 `usage` fields, 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.

## Install

```bash
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

```bash
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

```bash
# 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:

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

**Proactive polling loop** (every 30s):
1. **Checkpoint** — saves team state to disk (always recoverable)
2. **Soft prune** (at 45% context) — gentle prescription, no reload
3. **Hard prune** (at 75% context) — full prescription + optional reload

**Reactive overflow recovery** — kqueue/polling file watcher detects inbox-flood overflow within milliseconds, auto-prunes with escalating prescriptions, circuit breaker prevents loops.

**Token thresholds auto-detect** — 200K and 1M models detected automatically from session data. Override with `COZEMPIC_CONTEXT_WINDOW=1000000` if needed.

## Behavioral Digest

Cozempic extracts your corrections and persists them across compactions:

```bash
# 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

```bash
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 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()** — 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

## Example Output

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

## Changelog

### v1.5.0

- **`tool-result-age` strategy** — 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

### v1.4.0 / v1.4.1

- **Track 1 — Bug fixes**: `is_protected()` guard on all strategies, `isSidechain` preserved in envelope-strip, `output_tokens` in token formula, `parentUuid` re-linking, sibling tool_use protection
- **Track 2 — New strategies**: `compact-summary-collapse` (85-95%), `attribution-snapshot-strip`, microcompact-aware `tool-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 diagnose` shows cache hit rate
- **transcript_path**: hooks parse session path from payload for faster resolution
- Tests: 165 → 273

### v1.3.0 / v1.3.1

- Writer-safe live prune + sidecar session store
- Guard startup cleanup, updater fixes, MCP maintenance

### v1.2.0 — v1.2.8

- 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

## Contributing

Contributions welcome. To add a strategy:

1. Create a function in the appropriate tier file under `src/cozempic/strategies/`
2. Decorate with `@strategy(name, description, tier, expected_savings)`
3. Return a `StrategyResult` with a list of `PruneAction`s
4. Add to the appropriate prescription in `src/cozempic/registry.py`

## License

MIT — see [LICENSE](LICENSE).

Built by [Ruya AI](https://ruya.ai).
