Context cleaning toolkit for Claude Code — prunes bloated sessions with 13 composable strategies and protects Agent Teams from context loss.
Overview#
Cozempic is a context management toolkit for Claude Code developed by Ruya AI (maintainer: Junaid Qureshi), released under the MIT license. It addresses session file (JSONL) bloat that typically grows to 8-46MB by identifying and removing noise data such as progress tick messages, duplicate thinking blocks, stale file reads, and metadata bloat to improve effective token utilization.
Core Features#
Context Bloat Cleaning#
- 13 Composable Strategies: progress-collapse, file-history-dedup, metadata-strip, thinking-dedup, etc.
- Three-Tier Prescription System:
- gentle: 3 strategies, 5-8% savings, minimal risk
- standard: 7 strategies, 15-20% savings, low risk
- aggressive: 13 strategies, 20-25% savings, moderate risk
- Safety Mechanisms: Default dry-run mode; automatic backups; preserves uuid/parentUuid to maintain session DAG integrity
Token-Aware Diagnostics#
- Reads precise token counts from Claude usage field
- Displays token count and context usage percentage bar per command
- Supports setting guard thresholds in token units
Agent Teams 5-Layer Protection#
| Layer | Mechanism | Trigger |
|---|---|---|
| Continuous checkpoint | Periodic team state saving | Every N seconds |
| Hook-driven checkpoint | Event-driven saving | Task spawn/TaskCreate/TaskUpdate/PreCompact/Stop |
| Tiered pruning | Graduated pruning | Soft threshold gentle pruning → hard threshold full pruning |
| Reactive overflow recovery | kqueue/polling file monitor | inbox-flood overflow detection, millisecond response |
| config.json ground truth | Read authoritative team state | ~/.claude/teams/*/config.json |
Claude Code Plugin Integration#
- Slash Commands:
/cozempic:diagnose,/cozempic:treat,/cozempic:reload,/cozempic:guard,/cozempic:doctor - MCP Tools: diagnose_current, estimate_tokens, list_sessions, treat_session, list_strategies
- Hooks: SessionStart starts guard daemon; PostToolUse/PreCompact/Stop trigger checkpoint
Installation & Quick Start#
# PyPI installation
pip install cozempic
# Enable as Claude Code plugin
/plugin marketplace add Ruya-AI/cozempic
/plugin install cozempic
# Initialize configuration
cozempic init
CLI Command Reference#
cozempic init # Initialize (configure hooks and slash commands)
cozempic list # List all sessions
cozempic current --diagnose # Diagnose current session
cozempic treat current # Dry-run standard prescription
cozempic treat current --execute # Execute pruning (with backup)
cozempic treat <session_id> -rx aggressive --execute # Aggressive pruning
cozempic checkpoint --show # Save and display team state
cozempic guard --daemon # Start background daemon
cozempic guard --threshold 50 --threshold-tokens 180000 # Custom thresholds
cozempic reload -rx gentle # Prune and auto-recover
cozempic doctor [--fix] # Health check
Technical Implementation#
- Languages: Python 99.7%, Shell 0.3%
- Dependencies: Zero external dependencies, Python 3.10+ standard library only
- MCP Server: Based on fastmcp, runs via uv
- Guard Daemon: Polling check + kqueue/stat polling dual mode
Project Structure#
src/cozempic/
├── strategies/ # 13 cleaning strategy implementations
├── registry.py # Prescription registration and composition
├── guard/ # Guard Daemon
├── checkpoint/ # Team state snapshots
└── mcp/ # MCP Server
plugin/ # Claude Code plugin
tests/ # Tests