should-compact

should-compact

Compaction is the lossiest operation an agent session has, and harnesses fire it on the wrong signal. Claude Code compacts on token pressure: measured across 235 real events on this operator's machine, the median compaction fired at 998,289 tokens of a 1M window — 99.8% full. A later 90-day recount (n=258 main-chain events) put the median at 987,636 — same finding, larger sample. Token pressure knows nothing about whether the agent is between tasks or three files into a refactor.

Read that as a fraction of the wall, never as an absolute. The wall moves: a proxy that arms autoCompactWindow or CLAUDE_CODE_AUTO_COMPACT_WINDOW sets it, and once one does the same "compacts when full" behaviour arrives at a much smaller number. Recounted over seven days and 3,778 transcripts on the same machine, 1,522 automatic compactions had a median pre-context of 267,313 tokens — a quarter of the earlier figure, from an identical trigger against a lower wall. Every headroom judgement here is therefore made against the caller-supplied wall, and a gate that substitutes the hardware window for it will read a session at its limit as one with 700k to spare.

This skill scores the thing token pressure cannot see: is the work at a seam right now?

Running as a Gemini model? Read gemini.md in this directory first, then follow this file with the overrides it names. It binds the five signals and the score/verdict/block consistency rules to a readback before the object is emitted, because the PreCompact hook branches on score alone. Other models skip it.

What you produce

Two things, in this order. The reasoning comes first because writing the deduction before the number is what makes a small model's score stable — asked for a bare score it anchors on the first plausible digit and rationalises afterwards.

{
  "reasoning": "Last turn wrote plan-0406.md and exited plan mode. No tool call is open. Two files were read this session and neither is half-edited. Log shows the research phase closed at 12:04.",
  "signals": {"open_tool_chain": false, "unsaved_edit": false, "active_error": false, "below_floor": false, "at_the_wall": false},
  "boundary": "planning→implementation",
  "score": 8,
  "verdict": "compact",
  "block": false
}