A transparent Claude Code plugin that keeps sessions coherent across context compaction: structured state capture before /compact, recovery injection right after compaction and on --resume, plus a self-contained context-usage warning. It never touches the compaction algorithm itself — official hooks only.
Derived from u-ichi/compact-plus (MIT) with three changes:
- Self-contained warnings — compact-plus relies on a statusline script from the author's separate dotfiles repo for its context-usage warning, so it never fires on a plugin-only install. compact-ops computes usage directly from the transcript's latest assistant
message.usageinside a UserPromptSubmit hook. - Persistent state — state files live under
~/.claude/compact-ops/(organized per project cwd, 30-day retention) instead of$TMPDIR, so they survive reboots. - Cross-session recovery — a SessionStart hook injects recovery guidance on
--resumeas well as right after compaction (via thecompactmatcher, replacing the PostCompact-marker → UserPromptSubmit indirection), with a fallback to the newest state file from the same project (72h freshness cap).
Also: the manual /compact-ops skill's session-id detection script is bundled with the plugin, and the default LLM backends are Claude-only (Sonnet primary, Haiku fallback).
git clone https://github.com/kenimo49/compact-ops.git
claude plugin marketplace add /path/to/compact-ops --scope user
claude plugin install compact-ops@compact-ops-localRequires Claude Code v2.x, jq, and the claude CLI as the LLM backend. Linux and macOS are supported (hashing falls back md5sum → md5 → shasum; no GNU-only options).
After installing, just run /compact (or let auto-compact fire) — no extra steps.
Standard Claude Code compresses the whole conversation into a single built-in summary and discards the old messages. When that summary comes out thin, the post-compaction agent forgets which files it was editing, what was decided (and rejected), and which approaches already failed. compact-ops does not replace that summary — it adds insurance around it:
| Moment | Standard Claude Code | With compact-ops |
|---|---|---|
| Context usage passes 60% (configurable) | No warning; auto-compact hits without notice | One-shot reminder to /compact at a clean stopping point, plus a 3-line recitation of the current plan / phase / latest decision |
| At compact time | Built-in prompt writes the summary (not controllable) | Same compression runs, plus the transcript is backed up and a separate LLM (Sonnet) writes a 10-heading state file |
| Right after compact | The agent continues from the summary alone | Recovery guidance is injected into the fresh context: the state file, a "re-read the originals first" note, and the list of invoked skills |
| After the session ends | The summary exists only inside that session | The state file persists under ~/.claude/compact-ops/ for 30 days and is re-injected on claude --resume, even across reboots |
| If a hook fails | — | Fail-open: standard compaction proceeds untouched |
So the post-compaction agent restarts with two anchors instead of one: the standard summary plus a structured state file holding the active plan, remaining tasks, decisions with reasons, blockers, files being edited, and failed attempts. The state file is a plain markdown file, so you can also read it yourself to see what was handed over.
What does not change: the compaction algorithm and the standard summary itself are untouched; the state file is never more authoritative than the original project files; and each compact costs one extra LLM call (default Sonnet — downgrade to Haiku or disable via COMPACT_OPS_PRIMARY_BACKEND).
- PreCompact: back up the transcript (gzip) and write a 10-heading state file via an LLM (
~/.claude/compact-ops/state/<cwd_hash>/<session_id>.md); the LLM output is only written after all 10 headings validate, otherwise the previous state is kept - PostCompact: reset the warning cooldown
- SessionStart (compact): inject recovery guidance into the fresh post-compaction context
- SessionStart (resume): inject this session's state, or the project's newest recent state
- UserPromptSubmit: compute context usage from the transcript; above the threshold (default 60%), inject a one-shot
/compactreminder plus a 3-line state recitation
All hooks fail open; set COMPACT_OPS_DEBUG=1 to log swallowed failures under ~/.claude/compact-ops/logs/. Configuration is via COMPACT_OPS_* env vars in ~/.claude/settings.json — see the Japanese README for the full table.
Security and retention: state files and backups carry raw conversation content (secrets echoed by tools included), so everything is created with umask 077 (dirs 700 / files 600). State is pruned after 30 days; backups keep at most 20 per session and 30 days. Known limitation: the usage warning can only be computed on UserPromptSubmit, so an auto-compact that fires before your next prompt gets no advance warning (state capture still runs).
Part of a small set of tools for keeping long Claude Code sessions coherent. Siblings: claude-shift (multi-account switch + usage observer) and hook-chain-lens (diagnostic lens for merged hook chains across user / project / plugin scopes), all grouped under kenimoto Claude Code Kit.
MIT. Contains code derived from u-ichi/compact-plus (MIT).
If this project saved you time, you can sponsor its continued maintenance.