Cozempic CLI
A CLI that strips ballast from Claude Code sessions, watches context with a background guard and preserves Agent Teams state
- 427 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Writes hooks into Claude Code settings globally and starts a background process in every session
- Rewrites session files and terminates the Claude Code process so it can resume after cleaning
- Updates itself from PyPI, so new code arrives without your review, and sends anonymous usage counters
Install
- Works in
Manual install
uv tool install cozempicA persistent install with the command always on PATH. `pipx install cozempic`, `npm install -g cozempic` and `pip install cozempic` work too.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Writes hooks into Claude Code settings globally and starts a background process in every session
- Rewrites session files and terminates the Claude Code process so it can resume after cleaning
- Updates itself from PyPI, so new code arrives without your review, and sends anonymous usage counters
This is third-party code. Review the repository files before installing.
What it does
Cozempic strips ballast from Claude Code sessions. A session file grows as you work: progress records, thinking blocks, stale file reads, repeated CLAUDE.md injections, base64 screenshots and bulky tool outputs pile up. Cozempic removes this noise with 18 strategies in three sets (`gentle`, `standard`, `aggressive`) and leaves the conversation and decisions alone. By default commands run dry: `cozempic treat current` shows how much can be freed, and writing starts only with the `--execute` flag and after a backup. A background guard, `cozempic guard`, watches how full the context is. At 25, 55 and 80 percent it switches on stronger sets of strategies, and in an interactive session it warns first and restarts the session only in a pause between turns. For Agent Teams, Cozempic saves the team state before compaction and restores it after an overflow. The digest module picks corrections like «don't do X» out of your messages and writes them to Claude Code memory so they survive compaction. The `cozempic doctor` command finds and repairs corrupted sessions.
Who it is for. For developers who work in long Claude Code sessions, keep hitting autocompact or run agent teams and do not want to lose context.
Good fit when
- A Claude Code session has grown to tens of megabytes, and every request drags along progress ticks, old file reads and duplicate CLAUDE.md blocks
- You often hit autocompact and want to cut ballast ahead of time so the conversation stays intact
- An agent team is running, and autocompact wipes its coordination state
- A session will not resume or fails with a 400 error over lost tool results: `cozempic doctor --fix` repairs such cases
- You want to know what bloats a session: `cozempic current --diagnose` shows the sources of ballast and the token count
Not a fit when
- You work outside Claude Code: Cozempic is built for its session files
- You do not want background processes: after the first run the hooks and guard are enabled globally unless `COZEMPIC_NO_GLOBAL_INIT=1` is set
- Software versions on the machine must stay fixed without review: the package updates itself by default, so you would have to pin a version by hand
- The session is short and far from the context limit: there is nothing to clean
Example request
Show me what is bloating my current Claude Code session and do a dry run of the standard set without writingLimitations
- Cozempic edits Claude Code session files, and their format changes between client versions. For that reason the package updates itself from PyPI by default. Set `COZEMPIC_NO_AUTO_UPDATE=1` to stop updates or `COZEMPIC_PIN` to pin a version.
- A reload terminates the Claude Code process and resumes the session. The guard defers it while a Workflow, a background subagent, an agent team or an open tool call is running. In tmux and screen the session resumes in the same pane, in a plain terminal a new window opens.
- Python 3.10 or newer is required, with no external dependencies. Running through uvx without installing is fine for a trial, but the guard cannot start on its own from an ephemeral environment.
- The developer collects anonymous usage counters; `COZEMPIC_NO_TELEMETRY=1` turns them off.
How to disable. The `cozempic uninstall` command reverses init and removes the hooks and slash command. The `--project`, `--all` and `--purge` flags choose the scope. The package itself goes away the way you installed it: `pipx uninstall cozempic`, `uv tool uninstall cozempic` or `npm uninstall -g cozempic`.
FAQ
How do I install Cozempic for Claude Code?
Run `uv tool install cozempic`, `pipx install cozempic` or `npm install -g cozempic`. Hooks and the guard connect on first use. For the MCP tools and skills such as /cozempic:diagnose, run `/plugin marketplace add Ruya-AI/cozempic` and `/plugin install cozempic` inside Claude Code.
Is it safe to run cozempic treat?
The command runs dry by default and changes nothing without the `--execute` flag. A timestamped .jsonl.bak copy is created before any edit, writes are atomic, and compaction summaries and compact boundaries are never removed.
How do I turn off Cozempic auto-update and background hooks?
`COZEMPIC_NO_AUTO_UPDATE=1` stops updates while hooks and the guard keep running, `COZEMPIC_PIN` pins a reviewed version, and `COZEMPIC_NO_GLOBAL_INIT=1` leaves manual command-line use only, with no hooks and no daemon.
How is Cozempic different from Claude Code autocompact?
Autocompact summarizes history with losses. Cozempic cuts ballast with 18 strategies and leaves the conversation untouched, and the guard warns ahead of time: nudges come at 25, 55 and 80 percent of context.
How do I restore a session to its state before cleaning?
Before every write Cozempic puts a .jsonl.bak backup beside the session. Put it back in place of the session file. The `cozempic doctor` command also flags old backups that waste disk space and deletes them with `--fix`.
Discussion
No questions or reviews yet.
Related
CLI toolsAn environment for Claude Code that keeps context across sessions via hooks, ledgers and handoffs, orchestrates agents and saves tokens
A 7-rule CLAUDE.md template and session handoff commands so Claude Code keeps numbers and decisions through compaction
A self-improvement plugin for Claude Code, Codex and OpenCode: turns corrections into rules the agent follows in later sessions
Orchestration layer for Claude Code, Cursor and Codex: a board of 495 expert personas gives a verdict with named dissent, plus hundreds of skills
Multi-agent orchestration for Claude Code: teams, roles, autopilot and task routing across skills and subagents
An operating layer for Claude Code and Codex: one /do entry point, project memory across sessions, safety hooks, cost telemetry and parallel agents
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Cozempic (this entry) | no | 427 | ||
| Token Optimizer | no | 2,780 | cuts extra tokens and shows cost, while Cozempic's core tool is cleaning the session file with 18 strategies | |
| Context Mode | no | not required | 32,711 | keeps large tool output out of the context, while Cozempic cleans the session file already accumulated |
| fast-jev-compaction | no | 7,795 | a compaction plugin that drops unneeded tool calls, while Cozempic is a standalone CLI with a guard, doctor checks and Agent Teams protection |
README in short
The page opens with the problem and a feature list, then gives install options and a quick start. Next come a strategy table with expected savings, a section on the guard and its fill thresholds, the digest of corrections and a table of doctor checks. The end has the command list, the hook list, safety rules and a changelog.