smartcompact

Human-in-the-loop context compaction for Claude Code. You pick which conversation turns survive a compaction — a SessionStart hook re-injects them deterministically after every compact and resume, so they can't be summarized into oblivion.

The problem

Compaction is lossy, and it compounds. Round 2 summarizes round 1's summary, round 3 summarizes that — a summary of a summary of a summary. The one result you actually care about, the reason you abandoned an approach, the instruction you told Claude to keep following — any of it can quietly evaporate, and you only notice when Claude contradicts itself three rounds later.

Existing tools solve this by automating it: an LLM guesses what mattered and writes a state file for you. That's fine until it guesses wrong — and you never got a say.

What smartcompact does differently

smartcompact is the manual answer. Before you compact, it shows you the actual moments from this conversation — a result you hit, a decision and its reason, a standing instruction — and asks which ones to pin. What you pick is written to disk as a dense summary and re-injected verbatim into context after every compaction, independent of whatever the summarizer decides to keep.

You decide what survives. Not a model.

If you'd rather never think about it, use an automatic tool. smartcompact is for when the cost of losing the wrong thing is high enough that you want to choose.

Install

/plugin marketplace add codeprakhar25/smartcompact
/plugin install smartcompact@smartcompact

That's it — the command and the re-injection hook are wired automatically. No settings.json edits, no symlinks.

Usage

/smartcompact            # pin turns, then hands you a ready-to-paste /compact line
/smartcompact save       # pin turns now, without compacting
/smartcompact recover X  # dig lost detail on topic X out of the raw transcript

/smartcompact and save need an interactive session (they ask you questions — headless -p mode has no way to answer and will hang). recover and the reinjection hook work everywhere.

Typical flow: run /smartcompact when your context is getting full. It surfaces the moments worth keeping from this conversation and asks what to pin. You pick. It writes the pins (finding your session and compaction round automatically) and hands you a tuned /compact line. You paste it. The compaction lands — and your pinned turns come back automatically, marked as authoritative.

Walkthrough

> /smartcompact

  Which of these should be pinned to survive compaction?  (select any)
  [x] Result: eval pipeline hit 84% — structural reformulation gave no lift
  [ ] Decision: dropped the proxy approach (double-counts tokens on retry)
  [x] Your rule: never store full transcripts, detailed summaries only
  [ ] Artifact: hooks/pin-inject.js — the deterministic re-inject mechanism

  What should this compaction prioritize?
  > Keep final decisions + next steps; compress exploration

  ✓ Pinned 2 items to ~/.claude/smartcompact/<session>.md
  Paste this to compact:

     /compact Structure the summary as a Durable ledger (append-only) +
     Recent narrative. Prioritize: final decisions + next steps.

> /compact ...
  Compacting... ✓

  ⎿ SessionStart:compact hook — "Injecting pinned context..."

  PINNED CONTEXT — user explicitly saved these via /smartcompact.
  Treat as authoritative; they override anything compaction dropped:
    • Result: eval pipeline hit 84% — structural reformulation gave no lift
    • Your rule: never store full transcripts, detailed summaries only

The pinned lines are back in context after the reset — guaranteed, not hoped for.

How it works

Two mechanisms, each doing only what it can do reliably:

1. Pins → deterministic re-injection. Pins are dense summaries written to <config-dir>/smartcompact/<session_id>.md. The SessionStart hook (matcher compact|resume) reads that file and prints it to stdout, which Claude Code injects into the fresh context. Because it's keyed by session_id (constant across a session's compactions), your pins follow the conversation and can't be dropped by the summarizer. Session-scoped: new sessions start clean; stale pin files self-delete after 14 days.

2. Ledger / narrative split. The /compact line smartcompact composes tells the summarizer to keep a Durable ledger (append-only facts, decisions, paths — merged rather than re-shortened once it grows large) separate from a Recent narrative (freely re-summarized). This stops the compounding summary-of-a-summary decay for everything you didn't explicitly pin.

The transcript on disk is append-only and never truncated by compaction, so recover can always dig the raw messages back out for anything that was neither pinned nor kept.

Built to be cheap at the worst moment

/smartcompact runs when your context is nearly full — exactly when every extra model round trip is slowest and most expensive. So the whole flow is one question and one Bash call: the model picks pin candidates from context it already has (no discovery commands, no transcript reads), asks you, and pipes your picks into scripts/pin.js — which finds the session, counts compaction rounds, and appends, all in that single call. recover likewise parses the transcript in a script and returns only truncated matching snippets — a single raw transcript line can be tens of KB of tool output, and none of that ever enters your context.

Nothing leaves your machine. No network calls, no external service, no dependencies beyond Node (already required by Claude Code).

License

MIT — see LICENSE.