cozempic 0.5.2

Context cleaning for Claude Code — remove the bloat, keep everything that matters, protect Agent Teams from context loss

Cozempic

Context cleaning for Claude Code — remove the bloat, keep everything that matters, protect Agent Teams from context loss.

What gets removed

Claude Code context fills up with dead weight that wastes your token budget: hundreds of progress tick messages, repeated thinking blocks and signatures, stale file reads that were superseded by edits, duplicate document injections, oversized tool outputs, and metadata bloat (token counts, stop reasons, cost fields). A typical session carries 8-46MB — most of it noise. Cozempic identifies and removes all of it using 13 composable strategies, while your actual conversation, decisions, tool results, and working context stay untouched.

Agent Teams context loss protection

When context gets too large, Claude's auto-compaction summarizes away critical state. For Agent Teams, this is catastrophic: the lead agent's context is compacted, team coordination messages (TeamCreate, SendMessage, TaskCreate/Update) are discarded, the lead forgets its teammates exist, and subagents are orphaned with no recovery path. (#23620, #23821, #24052, #21925)

Cozempic prevents this with five layers of protection:

1. Continuous checkpoint — saves team state to disk every N seconds so it's always recoverable
2. Hook-driven checkpoint — fires after every Task spawn, TaskCreate/Update, before compaction, and at session end
3. Tiered pruning — soft threshold gently trims bloat without disruption; hard threshold does full prune + optional reload
4. Reactive overflow recovery — kqueue/polling file watcher detects inbox-flood overflow within milliseconds, auto-prunes with escalating prescriptions, and resumes the session (~10s downtime vs permanently dead). Circuit breaker prevents infinite recovery loops. (#23876)
5. Config.json ground truth — reads ~/.claude/teams/*/config.json for authoritative team state (lead, members, models, cwds)

Zero external dependencies. Python 3.10+ stdlib only.

Install

pip install cozempic

Or run directly:

git clone https://github.com/Ruya-AI/cozempic.git
cd cozempic
pip install -e .

Setup

After installing, run init from your project directory:

cd your-project/
cozempic init

That's it. This auto-wires everything:

1. Guard daemon auto-start — SessionStart hook spawns cozempic guard --daemon when Claude Code opens. Background process, PID file prevents double-starts, logs to /tmp/cozempic_guard_*.log
2. Checkpoint hooks — PostToolUse[Task|TaskCreate|TaskUpdate], PreCompact, Stop capture team state at every critical moment
3. /cozempic slash command — installed to ~/.claude/commands/ for in-session diagnosis and treatment

Idempotent — safe to run multiple times. Existing hooks and settings are preserved. No second terminal needed.

Quick Start

# One-time setup: wire hooks + slash command
cozempic init

# List all sessions with sizes
cozempic list

# Auto-detect and diagnose the current session
cozempic current --diagnose

# Dry-run the standard prescription on current session
cozempic treat current

# Apply with backup
cozempic treat current --execute

# Go aggressive on a specific session
cozempic treat <session_id> -rx aggressive --execute

# Save team/agent state right now (no pruning, instant)
cozempic checkpoint --show

# Guard auto-starts on session open (after cozempic init)
# Or run manually with custom thresholds:
cozempic guard --threshold 50 -rx standard

# Run as background daemon (what the SessionStart hook uses):
cozempic guard --daemon

# Treat + auto-resume in a new terminal
cozempic reload -rx gentle

Session IDs accept full UUIDs, UUID prefixes, file paths, or current for auto-detection based on your working directory.

How It Works

Each type of bloat has a dedicated strategy that knows exactly what to remove and what to keep. Strategies are grouped into prescriptions — presets that balance cleaning depth against risk:

Prescription	Strategies	Risk	Typical Savings
gentle	3	Minimal	5-8%
standard	7	Low	15-20%
aggressive	13	Moderate	20-25%

Dry-run is the default. Nothing is modified until you pass --execute. Backups are always created automatically.

Strategies

#	Strategy	What It Does	Expected
1	progress-collapse	Collapse consecutive progress tick messages	40-48%
2	file-history-dedup	Deduplicate file-history-snapshot messages	3-6%
3	metadata-strip	Strip token usage stats, stop_reason, costs	1-3%
4	thinking-blocks	Remove/truncate thinking content + signatures	2-5%
5	tool-output-trim	Trim large tool results (>8KB or >100 lines)	1-8%
6	stale-reads	Remove file reads superseded by later edits	0.5-2%
7	system-reminder-dedup	Deduplicate repeated system-reminder tags	0.1-3%
8	http-spam	Collapse consecutive HTTP request runs	0-2%
9	error-retry-collapse	Collapse repeated error-retry sequences	0-5%
10	background-poll-collapse	Collapse repeated polling messages	0-1%
11	document-dedup	Deduplicate large document blocks	0-44%
12	mega-block-trim	Trim any content block over 32KB	safety net
13	envelope-strip	Strip constant envelope fields	2-4%

Run a single strategy:

cozempic strategy progress-collapse <session_id> -v
cozempic strategy thinking-blocks <session_id> --thinking-mode truncate

Commands

cozempic init                               Wire hooks + slash command into project
cozempic list [--project NAME]              List sessions with sizes
cozempic current [-d]                       Show/diagnose current session (auto-detect)
cozempic diagnose <session>                 Analyze bloat sources (read-only)
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/agent state to disk (no pruning)
cozempic guard [--threshold MB]             Tiered guard: checkpoint + soft/hard prune
cozempic guard --soft-threshold 25          Custom soft threshold (default: 60% of hard)
cozempic guard --no-reactive                Disable reactive overflow recovery
cozempic doctor [--fix]                     Check for known Claude Code issues
cozempic formulary                          Show all strategies & prescriptions

Use current as the session argument in any command to auto-detect the active session for your working directory.

Checkpoint — Instant Team State Snapshot

Save your current team/agent state to disk without pruning or modifying anything:

# Save team state
cozempic checkpoint

# Save and print the state
cozempic checkpoint --show

Output:

  Checkpoint: 6 subagents, 9 tasks -> team-checkpoint.md

Active agent team: agents

Subagents (6):
  - af9763f [Explore] — Explore memory system [completed]
    Result: Complete understanding of the memory system...
  - aa79e90 [Explore] — Explore platform adapters [completed]
    Result: Comprehensive technical summary of platform...
  ...

Shared task list:
  - [COMPLETED] Fix team detection
  - [IN_PROGRESS] Add continuous checkpoint
  - [PENDING] Update README

What gets detected

Cozempic scans two data sources and merges them:

JSONL session file (runtime state):

Pattern	Source	What's Extracted
Task tool calls	Subagent spawns	agent_id, subagent_type, description, prompt
<task-notification>	Agent completion messages	status, summary, full result text
TaskCreate / TaskUpdate	Shared todo list	task_id, subject, status, owner
TaskOutput / TaskStop	Background agent management	agent status updates
TeamCreate / SendMessage	Explicit team coordination	team name, teammate roles

~/.claude/teams/*/config.json (ground truth):

Field	What's Extracted
name	Authoritative team name
leadAgentId	Lead agent identifier
leadSessionId	Lead agent's session UUID
members[].model	Model used by each teammate (e.g., claude-opus-4-6)
members[].cwd	Working directory for each teammate
members[].agentType	Role/type of each teammate

Config.json fields are authoritative — they override JSONL-inferred values. JSONL is authoritative for runtime state (subagent progress, task status, results).

The checkpoint is written to .claude/projects/<project>/team-checkpoint.md.

Guard — Continuous Protection

Guard is a background daemon with two complementary systems:

Proactive polling loop (every N seconds):

• Phase 1: Continuous checkpoint — extracts team state and writes to disk. Lightweight read-only scan. Team state is always recoverable even if Claude crashes. Also merges ~/.claude/teams/*/config.json as ground truth for team name, lead agent, member models, and working directories.
• Phase 2: Soft prune (at soft threshold) — when file size crosses the soft threshold, applies a gentle prescription to trim easy bloat. No reload — the session continues uninterrupted.
• Phase 3: Hard prune (at hard threshold) — applies the full prescription with team-protect, injects recovery messages, and optionally kills + resumes Claude.

Reactive overflow recovery (sub-second, enabled by default):

When agent team sessions go idle, Claude's InboxPoller can deliver all queued teammate messages at once, spiking the JSONL past the 200k token limit in seconds — faster than the polling loop can react. The reactive watcher uses kqueue (macOS, 0.04ms latency) or stat polling (Linux, 200ms) to detect this overflow within milliseconds. On detection:

1. Circuit breaker check — prevents infinite prune → resume → crash loops (max 3 recoveries in 5 minutes)
2. Escalating prescription — recovery #1 uses gentle, #2 uses standard, #3 uses aggressive
3. Pre-flight check — if post-prune estimate is still too large, skips resume
4. Team-protected prune → kill → auto-resume (~10s downtime vs permanently dead session)
5. Breaker trip — after 3 rapid recoveries, halts with a clear message and saves a final checkpoint

Disable with --no-reactive if needed. Zero impact on normal sessions — the watcher runs silently and fast-path exits for small files.

The soft threshold defaults to 60% of the hard threshold. This gives a two-phase degradation: trim early and often, escalate only when needed.

# Standard — run in a separate terminal
cozempic guard

# Custom thresholds and interval
cozempic guard --threshold 40 --soft-threshold 25 --interval 15 -rx standard

# Without auto-reload (just clean, no restart)
cozempic guard --threshold 50 --no-reload

# Disable reactive overflow recovery (polling only)
cozempic guard --no-reactive

# Aggressive at hard threshold, gentle at soft (automatic)
cozempic guard --threshold 30 -rx aggressive

Output:

  COZEMPIC GUARD v3
  ===================================================================
  Session:     abc123.jsonl
  Size:        5.4MB
  Soft:        30.0MB (gentle prune, no reload)
  Hard:        50.0MB (full prune + reload)
  Rx:          gentle (soft) / standard (hard)
  Interval:    30s
  Team-protect: enabled
  Checkpoint:  continuous (every 30s)
  Reactive:    enabled

  Guarding... (Ctrl+C to stop)

  [14:23:01] Checkpoint #1: 6 agents, 9 tasks, 121 msgs (5.4MB)
  [14:25:31] Checkpoint #2: 8 agents, 12 tasks, 156 msgs (6.1MB)
  [14:28:01] Checkpoint #3: 8 agents, 12 tasks, 189 msgs (7.2MB)
  [14:45:01] SOFT THRESHOLD: 30.2MB >= 30.0MB
             Gentle prune, no reload (cycle #1)
             Trimmed: 4.1MB saved
  [15:10:01] HARD THRESHOLD: 50.3MB >= 50.0MB
             Emergency prune with standard (cycle #1)
             Pruned: 12.4MB saved
             Team 'dev-agents' state preserved (87 messages)

On Ctrl+C, guard writes a final checkpoint before exiting.

How team-protect works

During prune (soft or hard):

1. Extract full team state from JSONL + ~/.claude/teams/*/config.json
2. Separate team messages from non-team messages
3. Prune only non-team messages using the prescription
4. Merge team messages back at their original positions
5. Inject a synthetic message pair confirming team state (Claude sees this as conversation history)
6. Save with backup, then optionally reload (hard only)

Hook Integration

For the strongest protection, wire cozempic checkpoint into Claude Code hooks. This captures team state at every critical moment — not just on a timer.

Add to your project's .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "cozempic checkpoint 2>/dev/null || true"
          }
        ]
      },
      {
        "matcher": "TaskCreate|TaskUpdate",
        "hooks": [
          {
            "type": "command",
            "command": "cozempic checkpoint 2>/dev/null || true"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cozempic checkpoint 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cozempic checkpoint 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

This checkpoints team state:

Hook	When	Why
PostToolUse[Task]	After every subagent spawn	Capture new agent immediately
PostToolUse[TaskCreate|TaskUpdate]	After todo list changes	Track task progress
PreCompact	Right before auto-compaction	Last chance to save state
Stop	Session end	Final checkpoint

Protection layers summary

Layer	Trigger	What it does
Hooks	Every Task/TaskCreate/TaskUpdate, PreCompact, Stop	Instant checkpoint to disk
Guard (checkpoint)	Every N seconds	Extract team state + config.json, write checkpoint
Guard (soft prune)	At soft threshold (default 60% of hard)	Gentle prune, no reload, no disruption
Guard (hard prune)	At hard threshold	Full prune + team-protect + optional reload
Guard (reactive)	Sub-second file watcher (kqueue/polling)	Detect inbox-flood overflow → escalating prune → kill → resume
Reload	Manual (cozempic reload)	One-shot prune + auto-resume
Checkpoint	Manual (cozempic checkpoint)	One-shot state save

Reload — Treat + Auto-Resume

Prune the current session and automatically resume Claude in a new terminal:

cozempic reload -rx gentle

This:

1. Treats the current session with the chosen prescription
2. Generates a compact recap of the conversation
3. Spawns a watcher that waits for Claude to exit
4. When you type /exit, a new terminal opens with claude --resume
5. The recap is displayed before the resume prompt

Doctor

Beyond context cleaning, Cozempic can check for known Claude Code configuration issues:

cozempic doctor        # Diagnose issues
cozempic doctor --fix  # Auto-fix where possible

Current checks:

Check	What It Detects
trust-dialog-hang	hasTrustDialogAccepted=true in ~/.claude.json causing resume hangs on Windows
oversized-sessions	Session files >50MB likely to hang on resume
stale-backups	Old .bak files from previous treatments wasting disk
disk-usage	Total session storage exceeding healthy thresholds

The --fix flag auto-applies fixes where safe (e.g., resetting the trust dialog flag, cleaning stale backups). Backups are created before any config modification.

Claude Code Integration

Slash Command

Cozempic ships with a /cozempic slash command that's automatically installed to ~/.claude/commands/ when you run cozempic init. It works in any Claude Code project.

Type /cozempic in any session to get an interactive menu:

1. Diagnose — Analyze bloat sources and recommend a prescription (read-only, no changes)
2. Treat & Reload (Recommended) — Diagnose, prune session, and auto-open a new terminal with clean context
3. Treat Only — Diagnose and prune session in-place (you resume manually with claude --resume)
4. Guard Mode — Start a background sentinel that auto-prunes before compaction kills agent teams

You can also skip the menu with arguments: /cozempic diagnose, /cozempic treat, /cozempic guard, or /cozempic doctor.

The slash command is kept up-to-date — running cozempic init again after upgrading will update it if a newer version is available.

SessionStart Hook (Optional)

To persist the session ID as an environment variable for use in scripts and other hooks:

cp .claude/hooks/persist-session-id.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/persist-session-id.sh

Add to your .claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/persist-session-id.sh"
      }]
    }]
  }
}

This makes $CLAUDE_SESSION_ID available in all Bash commands during the session.

Safety

• Always dry-run by default — --execute flag required to modify files
• Timestamped backups — automatic .bak files before any modification
• Never touches uuid/parentUuid — conversation DAG stays intact
• Never removes summary/queue-operation messages — structurally important
• Team messages are protected — guard and checkpoint never prune Task, TaskCreate, TaskUpdate, TeamCreate, or SendMessage tool calls
• task-notification results preserved — agent completion results (the actual output) are captured and checkpointed
• Strategies compose sequentially — each runs on the output of the previous, so savings are accurate and don't overlap

Example Output

  Prescription: aggressive
  Before: 29.56MB (6602 messages)
  After:  23.09MB (5073 messages)
  Saved:  6.47MB (21.9%) — 1529 removed, 4038 modified

  Strategy Results:
    progress-collapse              1.63MB saved  (5.5%)  (1525 removed)
    file-history-dedup              2.0KB saved  (0.0%)  (4 removed)
    metadata-strip                693.9KB saved  (2.3%)  (2735 modified)
    thinking-blocks                 1.11MB saved  (3.8%)  (1127 modified)
    tool-output-trim               1.72MB saved  (5.8%)  (167 modified)
    stale-reads                   710.0KB saved  (2.3%)  (176 modified)
    system-reminder-dedup          27.6KB saved  (0.1%)  (92 modified)
    envelope-strip                509.2KB saved  (1.7%)  (4657 modified)

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 PruneActions
4. Add to the appropriate prescription in src/cozempic/registry.py

from cozempic.registry import strategy
from cozempic.types import Message, PruneAction, StrategyResult

@strategy("my-strategy", "What it does", "standard", "1-5%")
def my_strategy(messages: list[Message], config: dict) -> StrategyResult:
    actions = []
    # ... analyze messages, build PruneAction list ...
    return StrategyResult(
        strategy_name="my-strategy",
        actions=actions,
        # ...
    )

License

MIT - see LICENSE.

Built by Ruya AI.