convez.ai
SkillProdutividadeIntermediário
Ruya-AI

Cozempic

Ruya-AI/cozempic

Remove bloat de sessões Claude Code, mantém contexto limpo e protege Agent Teams

Ver no GitHub
BomPluginScore · de 0 a 100

Skill para limpeza de contexto em Claude Code que remove bloat de sessões (ticks de progresso, blocos de thinking, screenshots em base64, outputs duplicados) mantendo a conversa e decisões intactas. Funciona com daemon guardião automático e 18 estratégias de pruning em 3 níveis, protegendo Agent Teams de perda de contexto.

Instalação

$npx convez-ai Ruya-AI/cozempic

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
429
Forks
42
Acompanhando
3
Saúde
37%
Último commit
há 4 meses
Versão
v1.8.39
Issues abertas
17
Contribuidores
14

Casos de uso

  • Reduzir tokens de sessões inchadas (8-46MB de ruído)
  • Proteger Agent Teams de compactação com perda de estado
  • Automatizar limpeza contínua de contexto com daemon guardião
  • Recuperar conversas longas sem cair em autocompact lossy

Veredito

Ferramenta sólida e madura (50k+ usuários, v1.8.30) que resolve um problema real e frequente em sessões longas de Claude Code. O daemon guardião automático, detecção de contexto 1M e proteção de Agent Teams são diferenciais claros; zero dependências externas é um ponto forte.

README

A tradução para o português deste README ainda está na fila.

Cozempic

Downloads Version License

50,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
  • 13 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
  • 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 / uvx — no install needed, run on demand (recommended)
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.

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

#StrategyTierWhat It DoesExpected
1compact-summary-collapsegentleRemove all pre-compaction messages (already in the summary)85-95%
2attribution-snapshot-stripgentleStrip attribution-snapshot metadata entries0-2%
3progress-collapsegentleCollapse consecutive and isolated progress tick messages40-48%
4file-history-dedupgentleDeduplicate file-history-snapshot messages3-6%
5metadata-stripgentleStrip token usage stats, stop_reason, costs1-3%
6thinking-blocksstandardRemove/truncate thinking content + signatures2-5%
7tool-output-trimstandardTrim large tool results (>8KB or >100 lines), microcompact-aware1-8%
8tool-result-agestandardCompact old tool results by age — minify mid-age, stub old10-40%
9stale-readsstandardRemove file reads superseded by later edits0.5-2%
10system-reminder-dedupstandardDeduplicate repeated system-reminder tags0.1-3%
11tool-use-result-stripstandardStrip toolUseResult envelope field (Edit diffs, never sent to API)5-50%
12image-stripaggressiveStrip old base64 image blocks, keep most recent 20%1-40%
13http-spamaggressiveCollapse consecutive HTTP request runs0-2%
14error-retry-collapseaggressiveCollapse repeated error-retry sequences0-5%
15background-poll-collapseaggressiveCollapse repeated polling messages0-1%
16document-dedupaggressiveDeduplicate large document blocks (CLAUDE.md injection)0-44%
17mega-block-trimaggressiveTrim any content block over 32KBsafety net
18envelope-stripaggressiveStrip constant envelope fields (cwd, version, slug)2-4%

Prescriptions

PrescriptionStrategiesRiskTypical Savings
gentle5Minimal85-95% (with compact boundary)
standard11Low25-45%
aggressive18Moderate35-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:

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

4-tier proactive pruning (every 30s):

TierThresholdActionReload?
Soft25%gentle file cleanupNo
Hard55%standard pruneYes (interactive: at a breakpoint; deferred if agents active)
Hard280%aggressive pruneYes (gated by the safe-point check)
User90%manual aggressiveYes

Interactive sessions — instead of a surprise reload mid-work, the guard surfaces a nudge and reloads only once you pause between turns, after warning you. Near the wall (≈88%) it reloads even mid-turn — a higher-fidelity prune beats hitting autocompact. Detection is automatic (COZEMPIC_INTERACTIVE=auto); on/off force it. Headless/CI sessions reload immediately as before.

Safe-point reload — a reload terminates and resumes the Claude process, so the guard validates first: if a Workflow, a background subagent, an agent team, or an open tool call is in flight, the reload defers (read-only checkpoint) rather than destroying that work. Tune the near-wall force point with COZEMPIC_FORCE_RELOAD_PCT (default 0.88).

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

tmux/screen — reload resumes in the same pane via send-keys. Plain terminals open a new window.

Token thresholds auto-detect — 200K and 1M models detected automatically. Override with COZEMPIC_CONTEXT_WINDOW=200000 for Pro plan.

Behavioral Digest

Cozempic extracts your corrections and persists them across compactions:

# 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")
  • All corrections start as "pending" and activate after 2 occurrences (prevents one-shot noise from polluting the digest)
  • 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

cozempic doctor        # Diagnose issues
cozempic doctor --fix  # Auto-fix where possible
CheckWhat It DetectsAuto-Fix
trust-dialog-hangResume hangs on WindowsReset flag
claude-json-corruptionTruncated/corrupted JSONRestore from backup
corrupted-tool-usetool_use.name >200 charsParse and repair
orphaned-tool-resultstool_result missing matching tool_use — causes 400 errorsStrip orphans
zombie-teamsStale team directories with dead agentsRemove stale dirs
oversized-sessionsSession files >50MB—
stale-backupsOld .jsonl.bak files wasting diskDelete old backups
disk-usageSession 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 self-update                        Upgrade to latest version from PyPI
cozempic formulary                          Show all strategies & prescriptions

Hook Integration

After cozempic init, these hooks are wired automatically:

HookWhenWhat
SessionStartSession opensGuard daemon + digest inject
PostToolUse[Task]Agent spawnTeam checkpoint
PostToolUse[TaskCreate|TaskUpdate]Todo changesTeam checkpoint
PreCompactBefore compactionCheckpoint + digest flush
StopSession endCheckpoint + 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.8.23

  • Hardened numeric input validation — NaN, infinity, and non-representable huge integers are now rejected with a clear error at every CLI flag, COZEMPIC_* env var, and config field (a NaN threshold would otherwise silently disable the gate it controls). Thanks to @ynaamane (#116), and folded in the matching fix for the interactive-guard reload-grace knob
  • Standing adversarial QA fleet — docs/qa-fleet.md + a corpus-driven regression test so this whole class can't regress

v1.8.22

  • Interactive "prune now?" nudge — non-blocking heads-up at 25% / 55% / 80% context (once per tier, with hysteresis so it never nags), recommending cozempic reload. Brings cozempic's higher-fidelity prune+resume to interactive sessions without surprise reloads. Tunable via COZEMPIC_NUDGE_PCTS; silence with COZEMPIC_NUDGE_OFF=1
  • Interactive-safe reload — warns first, then reloads only at an idle breakpoint (never mid-turn); near the wall (COZEMPIC_FORCE_RELOAD_PCT, default 88%) it reloads even mid-turn. Headless/CI behaviour unchanged
  • Safe-point protection — the guard never terminates-and-resumes through a running Workflow, background subagent, agent team, or open tool call; the reload defers instead so in-flight work is preserved
  • Interactivity detection — COZEMPIC_INTERACTIVE=auto|on|off
  • Efficient idle polling — exponential poll back-off when the session is quiet (COZEMPIC_IDLE_BACKOFF_CYCLES) and skips redundant no-op SOFT checkpoints

v1.7.1

  • cozempic reload --session <id|path> escape hatch when auto-detect fails in multi-agent sessions. Previously reload had no way to recover from ambiguous session detection, leaving users stuck. Matches guard --session.
  • Error message now names the flag to use (was "use an explicit session ID" with no instruction on how)
  • Auto-update message clarified: after upgrade, says "active on next run (this process still vX.Y.Z)" — users no longer think the upgrade failed when --version still prints the old number (the running Python process can't hot-swap its own code)

v1.7.0

  • Telemetry opt-out: COZEMPIC_NO_TELEMETRY=1 disables anonymous usage counters
  • Documented configuration: COZEMPIC_NO_AUTO_UPDATE, COZEMPIC_NO_TELEMETRY, COZEMPIC_CONTEXT_WINDOW env vars

v1.6.x

  • 4-tier pruning: soft (25%, no reload) → hard (55%, reload) → emergency (80%, aggressive reload) → user (90%, manual)
  • Agent-aware reload: defers reload at 55% when agents are running, forces at 80%
  • Same-terminal resume: tmux/screen users get /exit + claude --resume in the same pane
  • Clean messaging: only shows strategies that did something, 1-line hook status output
  • 1M default: Opus/Sonnet 4.5/4.6 default to 1M context (CC doesn't use [1m] suffix)
  • Auto-upgrade everywhere: SessionStart hook backgrounds pip install --upgrade cozempic on every session. MCP/plugin use uv run --upgrade. npm install.js always upgrades.
  • cozempic self-update: force-upgrade from PyPI regardless of install method (pip, uv, editable, clone)
  • Auto-updater fixed: removed TTY check (was blocking hook-triggered updates), tries uv → pip → pipx

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

Configuration

VariableDefaultEffect
COZEMPIC_CONTEXT_WINDOWauto-detectOverride context window size (e.g. 200000 for Pro plan)
COZEMPIC_NO_AUTO_UPDATEoffSkip automatic version checks. Not recommended — Claude Code ships frequent changes and cozempic updates keep strategies compatible with the latest session format.
COZEMPIC_NO_TELEMETRYoffSkip anonymous usage counters. Cozempic pings a simple counter on each prune — no personal data, session content, or identifiable information is sent. Helps us prioritize development.

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

License

MIT — see LICENSE.

Built by Ruya AI.

Ver o original no GitHub

Bom para

Relacionados