Compaction prep

/compaction-prep — survive a context compaction without losing the thread

With early auto-compaction enabled (the /compaction-prep:setup command sets the window to ~50% of the model's context so the agent stays in its sharp zone), compaction replaces the live message history with a lossy summary — it silently drops file paths, decisions, identifiers, and the tail of in-flight work. Two hooks bracket the boundary and point here: a pre-compaction warning (before the summary) and a post-compaction note (SessionStart, after the summary). Follow the matching section.

The warning hook tells you the exact checkpoint path to use — it looks like ~/.claude/checkpoints/<session_id>.md. Use the path it gave you; don't invent one.

PREPARE — when warned that compaction is imminent

You will keep working after the warning, and compaction may fire mid-turn. So the goal is not "finish first" — it's "make the current state recoverable from disk so the post-compaction agent can continue." Crucially, the warning does NOT mean compaction is guaranteed or on a timer — it fires only as you keep consuming context. Do NOT stop and wait for it (idling just defers it), and do NOT manufacture busywork to force it: checkpoint, then continue your real task — or, if you're genuinely done, just stop and it'll compact on the next turn. Do this now, before more reading:

1. Write/refresh the checkpoint file at the path the hook gave you. Capture what a lossy summary would drop:
   • The task/goal in one line, and where you are in it (done / in-progress / not-started).
   • Next concrete steps — the first action the resumed agent should take.
   • Load-bearing specifics: exact file paths, function/symbol names, IDs, flags, decisions made and rejected, constraints, command lines that work.
   • Pointers to large outputs already on disk (logs, generated files, results) — so they don't need to be re-held in context.
2. Keep big things on disk, not in context. Don't paste large file contents or command output back into the conversation near the threshold — that's what makes auto-compact thrash (refill instantly, abort after a few tries). Summarize and reference the path instead.
3. Don't block on the user and don't announce the checkpoint at length — write it and continue the actual task.

The pre-compaction hook also records the boundary and the raw pre-compaction transcript path under ~/.claude/checkpoints/, so work done between the warning and the actual compaction is still recoverable even if this checkpoint is slightly stale.

RECOVER — right after resuming from a compaction (SessionStart note fired)

The summary above you is lossy. Before continuing:

1. Read the checkpoint at the path the post-compaction note gave you (~/.claude/checkpoints/<session_id>.md). If it's missing, check the boundary log in ~/.claude/checkpoints/ for the pre-compaction transcript path.
2. Re-hydrate: re-read the key files / re-fetch the identifiers the checkpoint names. Don't trust the summary's paraphrase of load-bearing detail.
3. Resume from "next steps." Do not treat the compaction boundary as task completion — that's the classic failure mode. If a /goal or /loop is active, keep driving toward its condition.
4. If anything in the checkpoint conflicts with the summary, the checkpoint and the re-read files win (they're primary; the summary is derived).

Why this exists

Compacting early (e.g. at 50%) roughly doubles compaction frequency, so detail is lost twice as fast. The checkpoint + re-hydrate loop is what makes early compaction a net win (staying sharp) instead of a net loss (forgetting the thread).