Compact without forgetting.
Compaction keeps one summary. smart-compact makes sure your standing rules and open decisions are in it, checks each checkpoint against the last, and measures what rehydrating would cost before anything is wiped.
claude plugin marketplace add ryanonline1234/smart-compact- 01 · Fill
Context fills.
51k tokens of system prompt, tools and memory are fixed. The conversation grows on top: 40k here, 91k in all.
- 02 · Save
Checkpoint first.
/smart-compact:savewrites a checkpoint and measures every file its manifest lists, before anything is wiped. - 03 · Compact
Then compact.
When the turn ends, the plugin runs
/compact: 91k becomes 28k by the engine's count. Compaction puts the checkpoint back by itself. - 04 · Rehydrate
Rebuild if you want.
Your call.
/smart-compact:rehydratere-reads the manifest: ≈14.3k estimated at save, 15.2k when it ran.
- conversation · 40k tokens
- system prompt, tools, memory · 51k tokens
- checkpoint · 0.8k tokens
- docs/STATE.md · 7.6k measured
- src/auth.ts · 6.7k measured
- rehydrate adds ≈14.3k · 15.2k real
Rules and open decisions, checked.
Agents reading the author's 229 sessions found that what compaction lost was standing rules and the numbered decision lists a later "go with recs" answers, mostly at compactions Claude Code started on its own. So the plugin works on every compaction, not just the ones you start.
- Every compaction
- A summary contract rides on each one, Claude Code's own included: standing rules, open decisions with their recommendations verbatim, approvals with their conditions. In a forced automatic compaction it kept all three open questions in 3 of 3 runs; without it, none, in 3 of 3.
- The pending list
- The newest numbered list that asks something is captured mechanically and held until you answer it, so every compaction quotes it word for word and "go with recs" still points at it. In a test with three automatic compactions, it reached each one in 3 of 3 runs.
- Carry-forward guard
- A new checkpoint that silently drops a rule or open decision the previous one held is refused, and an answered question must quote what you said.
- Compactions you didn't start
- A fork of the session, the same model reading the same transcript with tools denied, writes the checkpoint beside the summary. The plugin checks and corrects it like a save.
The notice says what rehydrating costs.
Measured at save, then corrected for the files compaction already put back. You decide with numbers, not a guess.
smart-compact: compacted (91k → 28k tokens); the system prompt and tools come on top. Rehydrate would add ≈14k tokens, measured at save, budget 150k: files: 2 ≈14k measured: docs/STATE.md 7.6k; src/auth.ts 6.7k 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.
Every token count is calibrated.
Seven files, each read in a turn of its own on a real model; the cost is the context growth across the read, line numbers included. Sonnet 5.5 and Opus 5.5 counted identically. These are Read-tool figures, not general prose, which runs nearer 3.6. Against Claude Code's own estimate of 3 bytes per token, they run about 10% lower for markdown and 20% lower for code.
| File | Characters | Real tokens | Estimate | Error |
|---|---|---|---|---|
| Claude Code docs page (md) | 19,943 | 7,665 | 7,647 | −0.2% |
| Claude Code docs page 2 (md) | 9,228 | 3,545 | 3,464 | −2.3% |
| synthetic notes (md) | 8,710 | 3,108 | 3,244 | +4.4% |
| JavaScript library file | 19,060 | 8,452 | 8,602 | +1.8% |
| Python json/decoder.py | 12,872 | 5,642 | 5,756 | +2.0% |
| Python json/encoder.py | 16,148 | 6,433 | 7,200 | +11.9% |
| synthetic TypeScript | 15,190 | 7,530 | 6,685 | −11.2% |
| All seven | 101,151 | 42,375 | 42,598 | +0.5% |
What's new, and what isn't.
A survey of Claude Code, its mods and plugins, 14 other coding agents, agent-memory frameworks and 2026 papers. Not found means not in that survey.
- Injected instructions
- Other mods add them to automatic compactions too (bindwright compact-handoff, handoff-compact), as do Codex's compact_prompt and the Claude API.
- Checkpoints
- Saving before compaction: compact-plus, Token Optimizer, and MemGPT in 2023.
- Forks
- Forking the session at compaction: bindwright's shadow mode and Anthropic's background compaction. The fork itself is Claude Code's own.
- The guard
- Refusing a checkpoint that drops what the previous one held.
- The pending list
- Captured mechanically and held until answered.
- Checked forks
- A fork-written checkpoint corrected like a save, the stock summary kept.
- Measured rehydrate
- Skipping the files Claude Code already put back.
Two commands.
Requires Claude Code 2.1.309 or later with mods enabled, the default from 2.1.287. Tested end to end on 2.1.310 in the mode the desktop app runs sessions in. Settings are in /config.
claude plugin marketplace add ryanonline1234/smart-compactclaude plugin install smart-compact@smart-compact- /smart-compact:save [budget]
- Checkpoint, then compact when the turn ends. The budget caps a later rehydrate; default 150k.
- /smart-compact:rehydrate [path] [budget]
- Re-read the checkpoint and its manifest, skipping what is already in context. You start it, or the plugin does with autoRehydrate.
- suggestFrom · suggestTo
- A token band. Inside it, Claude offers the save right after a commit or a state-file write, and at the band's top otherwise.
- autoRehydrate
- off, after-save, or always: rehydrate on its own after a compaction, asking nothing.
- Reads
- files your checkpoint lists, the profile, the session transcript, HOME
- Runs
- /compact once per save; /smart-compact:rehydrate with autoRehydrate; read-only git at a compaction you didn't start
- Asks the model
- one fork of your session per compaction it didn't start, through your own client
- Writes
- checkpoints under ~/.claude/checkpoints, one small record per session in the plugin's store, transcript notices, a prompt suggestion
- Never
- other network calls; other file writes, unless you set SMART_COMPACT_TRACE to a folder