smart-compact

Enforcement for Claude Code's compaction: what you decided and told it to keep survives, checked rather than hoped for.

Site: smart-compact.vercel.app

When Claude Code compacts, one summary decides what survives. Measured over the author's sessions, what got lost was standing rules ("never deploy without asking") and pending decision lists, the numbered questions a later "go with recs" answers. smart-compact keeps both, and it checks that they were kept:

• Every compaction carries a summary contract, Claude Code's own automatic ones included. The contract asks for standing rules, open numbered decisions with their recommendations verbatim, and approvals with their conditions.
• The latest pending decision list is captured mechanically and quoted into the compaction instructions word for word, so "go with recs" still points at the same list afterwards.
• A checkpoint on disk, with a carry-forward guard. /smart-compact:save writes a checkpoint before compacting. The guard refuses a new checkpoint that silently drops a rule or open decision the previous one held. At a compaction you didn't start, a fork of the session writes the checkpoint alongside the summary, and the plugin checks and corrects it like a save.
• Rehydrating is measured, and yours to call: the plugin tells you what /smart-compact:rehydrate would put back and what it costs, minus the files Claude Code already re-attached.

/smart-compact:save          checkpoint to disk; compaction queued for the end of the turn
(automatic)                  the plugin runs /compact with a pointer to the checkpoint
/smart-compact:rehydrate     re-read the checkpoint and its manifest, up to a budget

After the compaction, the plugin's notice reads like this:

smart-compact: compacted (91k → 28k tokens); the system prompt and tools come on top. Checkpoint: ~/.claude/checkpoints/…/20261103T233304Z-bug-hunt.ckpt.md
Rehydrate would add ≈14k tokens, measured at save, budget 150k:
  files: 2 ≈14k measured — docs/STATE.md 7.6k (why it is listed); src/auth.ts 6.7k (why it is listed)
  checkpoint itself: already back
  already back after compaction, so skipped: src/decoder.py
Send /smart-compact:rehydrate to rebuild context from it, or keep working from the summary.

Install

Requires Claude Code 2.1.309 or later with mods (function hooks) enabled, the default from 2.1.287. Tested end to end on 2.1.310 in stream-json mode, the mode the desktop app runs sessions in.

claude plugin marketplace add ryanonline1234/smart-compact
claude plugin install smart-compact@smart-compact

Inside a session: /plugin marketplace add ryanonline1234/smart-compact, then /plugin install smart-compact@smart-compact, then /reload-plugins.

Commands

Command	What it does
/smart-compact:save [budget]	Writes a checkpoint, then compacts when the turn ends. budget caps what a later rehydrate re-reads; the default is 150k.
/smart-compact:rehydrate [path] [budget]	Reads the checkpoint and its manifest, skipping anything already in context, and reports what it re-read, what it skipped, and why. You start it, or the plugin does after a compaction when you turn on autoRehydrate.

Checkpoints are plain markdown in ~/.claude/checkpoints/<project-slug>/, keyed by the project's git root rather than the shell's directory. The newest ten are kept; older ones move to archive/.

What it keeps, and how

Built for sessions that run for days: many rounds of feedback, several compactions, decisions answered with a short "go with recs". Over 229 of the author's interactive sessions, agents reading the transcripts judged what was lost after compactions: standing rules and pending asks, in 7 of 35 compactions, 5 of them automatic. A scripted re-measurement (docs/05-session-study.md) reproduces the population and finds that 78% of "go with recs" replies answer a numbered list. The loss count does not hold up: two automated re-judges found 1 and 2 losses in 47 compactions, but missed at least one clear loss the agents had found. The rate in these sessions is uncertain, somewhere between about 4% and 20% (details in docs/05). It is one person's sessions, not a general result.

• The summary contract. The plugin adds instructions to every compaction of the main conversation:
  • keep standing rules, with their date and scope;
  • keep every open numbered question with its recommendation, verbatim;
  • keep approvals with their conditions, unfinished requests, iteration pointers and methods that worked;
  • keep the latest checkpoint's pointer.

This is the beginning of the README. Read the rest at the original. Read the full README ↗