Claude Code 上下文清理工具，通过 13 种可组合策略修剪会话膨胀数据，保护 Agent Teams 免受上下文丢失影响。
项目概述#
Cozempic 是由 Ruya AI（维护者 Junaid Qureshi）开发的 Claude Code 上下文管理工具，采用 MIT 许可证。它解决了 Claude Code 会话文件（JSONL）随使用快速膨胀至 8-46MB 的问题，通过识别并移除噪声数据（进度 tick 消息、重复 thinking 块、过期文件读取、元数据膨胀等）提升有效 token 利用率。
核心特性#
上下文膨胀清理#
- 13 种可组合策略：progress-collapse、file-history-dedup、metadata-strip、thinking-dedup 等
- 三级处方系统：
- gentle：3 策略，5-8% 节省，风险最小
- standard：7 策略，15-20% 节省，低风险
- aggressive：13 策略，20-25% 节省，中等风险
- 安全机制：默认 dry-run 模式；自动备份；保留 uuid/parentUuid 维持会话 DAG 完整性
Token 感知诊断#
- 从 Claude usage 字段读取精确 token 计数
- 每个命令显示 token 数和上下文使用百分比条
- 支持以 token 为单位设置 guard 阈值
Agent Teams 5 层防护#
| 层级 | 机制 | 触发条件 |
|---|---|---|
| Continuous checkpoint | 周期性保存团队状态 | 每 N 秒 |
| Hook-driven checkpoint | 事件驱动保存 | Task spawn/TaskCreate/TaskUpdate/PreCompact/Stop |
| Tiered pruning | 分级修剪 | 软阈值温和修剪 → 硬阈值完整修剪 |
| Reactive overflow recovery | kqueue/polling 文件监视 | inbox-flood 溢出检测，毫秒级响应 |
| config.json ground truth | 读取权威团队状态 | ~/.claude/teams/*/config.json |
Claude Code 插件集成#
- 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 启动 guard daemon；PostToolUse/PreCompact/Stop 触发 checkpoint
安装与快速开始#
# PyPI 安装
pip install cozempic
# 作为 Claude Code 插件启用
/plugin marketplace add Ruya-AI/cozempic
/plugin install cozempic
# 初始化配置
cozempic init
CLI 命令参考#
cozempic init # 初始化（配置 hooks 和 slash command）
cozempic list # 列出所有会话
cozempic current --diagnose # 诊断当前会话
cpzempic treat current # Dry-run 标准处方
cozempic treat current --execute # 执行修剪（带备份）
cozempic treat <session_id> -rx aggressive --execute # 激进修剪
cozempic checkpoint --show # 保存并显示团队状态
cozempic guard --daemon # 启动后台守护
cozempic guard --threshold 50 --threshold-tokens 180000 # 自定义阈值
cozempic reload -rx gentle # 修剪并自动恢复
cozempic doctor [--fix] # 健康检查
技术实现#
- 语言：Python 99.7%，Shell 0.3%
- 依赖：零外部依赖，仅使用 Python 3.10+ 标准库
- MCP Server：基于 fastmcp，通过 uv 运行
- Guard Daemon：轮询检查 + kqueue/stat polling 双模式
项目结构#
src/cozempic/
├── strategies/ # 13 种清理策略实现
├── registry.py # 处方注册与组合逻辑
├── guard/ # Guard Daemon
├── checkpoint/ # 团队状态快照
└── mcp/ # MCP Server
plugin/ # Claude Code 插件
tests/ # 测试