compact-ops

Three steps

1. claude plugin install compact-ops Clone the repo, add it as a local marketplace, install once.
2. /compact Compact as usual. PreCompact backs up the transcript and writes the state file automatically.
3. recovery injected The fresh context receives the state file, a reread-the-originals note, and the invoked-skills list.

Who it’s for

• Heavy Claude Code users whose sessions routinely cross one or more compactions per day
• Agent operators running long or scheduled sessions and picking them up next day with claude --resume
• Teams handing sessions over the state file is plain Markdown a human can read as a handoff note
• Hook authors a worked example of a plugin built on official hooks only, fail-open throughout

When to reach for it

• When auto-compact has eaten a decision mid-task more than once: the 60% warning lets you pick the moment yourself
• Before multi-day work: the state survives compaction, session close, and a PC reboot
• When the agent re-asks for an approval it already had, or retries an approach that already failed: those are exactly the fixed headings in the state file
• If you have ever told a post-compact agent "we already decided this", that is the incident this plugin exists for

Install

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-local

Requires Claude Code v2.x, jq, and the claude CLI as the LLM backend. Linux and macOS supported. After installing, just run /compact as usual; the hooks handle the rest.

What it does

• PreCompact: backs up the transcript (gzip, JSONL shrinks to about 1/10) and has an LLM write a 10-heading state file: active plan, decisions, blockers, editing files, failed attempts
• Right after compaction: injects the state file, a reread-the-originals note, and the list of invoked skills into the fresh context
• On claude --resume: the same recovery injection, with a fallback to the project’s latest state within 72 hours, surviving a PC reboot
• Context-usage warning computed by the plugin itself (default 60%): recommends /compact once, with a 3-line recitation of plan, phase, and latest decision
• State persists under ~/.claude/compact-ops/ with 30-day retention, organized per project; session_id is allowlist-validated before it touches a file path
• The LLM output is validated for all 10 headings before writing; invalid output keeps the previous state and fails open
• Derived from u-ichi/compact-plus (MIT), made self-contained: no external statusline scripts, Claude-only LLM backends (Sonnet primary, Haiku fallback)

With and without compact-ops

Same compaction algorithm, same built-in summary. The difference is everything around it.

Source: the project README. The compression algorithm itself is untouched; everything is official hooks bolted on from the outside.

What the state file looks like

Usage

# just compact as usual — hooks handle the rest
/compact

# arguments become priority guidance for the state writer
/compact keep every design decision

# tune via the env block in ~/.claude/settings.json
COMPACT_OPS_WARN_THRESHOLD=70
COMPACT_OPS_PRIMARY_BACKEND=""
COMPACT_OPS_DEBUG=1

Field-tested on its own release

The first beneficiary was the session that built it. Three moments from real use, not staged demos:

• During the v0.2.0 release work, the plugin’s own 60% warning fired at 67% inside the very session doing the release: the author wrote the warning and was saved by it the same night.
• Minutes later, a directory restructure broke three of its hooks mid-session. Compaction still completed untouched, because every hook is fail-open: the failure mode was tested in production by accident.
• This page you are reading was revised in a session that crossed two compactions, each time resuming from the state file it describes.

The release-day log, including the 67% warning and the triple hook failure, is written up in full on the project blog.

How it works →

Costs to know: each compact adds one LLM call for state generation (default Sonnet; switch to Haiku or disable via env). State files and backups contain the conversation verbatim; they are created with umask 077 (directories 700, files 600), stay on your machine, and are auto-deleted after 30 days.

Why this plugin exists

The built-in summary is decent at code. What it drops are operational facts: "the push was already approved", "this approach was tried and failed", "that number came from this file". When those vanish, the agent re-asks for approvals and retries dead ends, and you pay for the same work twice. compact-ops gives those facts their own fixed headings and stores them outside the summary. One design line is non-negotiable: the state file is never treated as more authoritative than your project files. An LLM summary trusted blindly by another LLM is just a faster game of telephone, so the recovery guidance always points back to the originals.

Alongside compact-plus and plain Claude Code

compact-ops is a derivative of u-ichi/compact-plus (MIT), which pioneered the write-structured-state-before-compact idea. The differences below are the reasons the derivative exists.

The core idea, a PreCompact hook calling a second LLM to write structured state, comes from compact-plus. The table lists the README-documented differences as of July 2026; if its assumptions match your setup, compact-plus is a fine choice.

FAQ

About the author

Built by Ken Imoto: 300+ technical articles across Zenn, Qiita, Dev.to and this site, 40+ books in 4 languages, 400K+ pageviews on Zenn and Qiita, 4 research papers on Zenodo, and creator of the LLMO Framework.

More about Ken →