Task-aware context monitor for Claude Code. Watches every turn, estimates how full your context window is, classifies what kind of work you're doing, and nudges you to /compact at a threshold tuned to that task — before output quality decays.
LLMs get worse as context fills up, well before they hit the hard token limit. Public long-context benchmarks show meaningful degradation starting around 30–50% of the window for reasoning-heavy tasks. Claude Code's built-in auto-compact only fires when the window is nearly exhausted — by that point, quality has already been sliding for a while.
context-compactor watches for you, classifies the session (code-editing, exploration, planning, or mixed), and advises you to compact at a decay-aware threshold for that task type.
Three hooks + one statusline:
UserPromptSubmit— on every turn, estimates current context fraction from the statusline cache, classifies the task, and emits one of three tiers:- below
advise_at— silent. advise_at ≤ fraction < prompt_at— injects a quiet advisory into Claude's context.fraction ≥ prompt_at— emits a user-visiblesystemMessageand an embedded "inform the user" framing insideadditionalContextso Claude relays it either way.
- below
PreCompact— clears per-session state when you run/compact, so we don't keep nagging.SessionEnd— best-effort cleanup.- Statusline script — taps the documented Claude Code statusline contract, captures
context_window.used_percentageinto a cache file, and passes through a short status line ({model} · {pct}% ctx).
| Task type | Advise (soft signal to Claude) | Prompt (user-visible nudge) |
|---|---|---|
| code_edit | 35% | 55% |
| exploration | 40% | 60% |
| planning | 45% | 65% |
| mixed | 35% | 55% |
These are initial educated guesses, not empirically calibrated. Easy to override — see Configuration below.
# In Claude Code
/plugin marketplace add https://github.com/romankhadka/context-compactor
/plugin install context-compactor
That's it. Node 18+ is required (you already have it if you run Claude Code). No npm install step — the plugin uses Node's stdlib only. The repo hosts its own .claude-plugin/marketplace.json, so one URL gets you both the marketplace and the plugin.
Optional. Create ~/.claude/plugins/cache/context-compactor/config.json:
{
"schema_version": 1,
"profiles": {
"code_edit": { "advise_at": 0.30, "prompt_at": 0.50 }
},
"suppression_turns": 6
}Any profile or global field you omit falls back to the defaults in config/defaults.json.
/compactor-status— prints the current session's estimate, task type, thresholds, and suppression state.
CONTEXT_COMPACTOR_DEBUG=1+claude --debug— prints a decision trace to stderr on every hook run.- Errors are logged to
~/.claude/plugins/cache/context-compactor/errors.log(size-rotated at 1 MB; no transcript contents).
- No network calls. No telemetry.
- Error logs carry only stack lines and hook names, never user text.
- State files carry only derived numbers: fractions, turn counts, task type.
MIT. See LICENSE.