Claude-initiated context compaction: working workaround + native implementation proposal
Background
Five separate issues have requested the ability for Claude to autonomously trigger context compaction:
- #16960: Auto-compact at sub-task level
- #28559: Native /compact tool for autonomous context management
- #33026: Allow Claude to self-initiate context compaction
- #38925: Programmatic context compaction trigger from hooks
- #39574: Compact tool for programmatic context compaction
All five were closed by the stale bot without resolution. This issue consolidates them, adds a working workaround available today, and proposes the minimal native change needed to make this robust.
---
Working Workaround (Available Today)
Adding the following to ~/.claude/CLAUDE.md causes Claude to surface /compact as a ghost-text prompt suggestion at appropriate moments, no code changes required:
## Context compaction
When any of the following conditions apply, end your response with the phrase
"This is a good point to compact." to signal that the user should run `/compact`:
- A planned compaction checkpoint has been reached
- A multi-phase plan is being executed and the current phase is complete
- A major phase of work has completed and a distinct new phase is about to begin
- The context has accumulated substantial content (tool output, debug logs,
exploration) that is unlikely to be needed going forward
- You judge that compacting now would preserve more useful context than waiting
for auto-compact to fire
The phrase triggers a `/compact` prompt suggestion, allowing the user to compact
with a single keypress rather than having to type the command manually.How it works
The prompt suggestion generator makes a separate API call after each response to predict what the user will type next. This call includes the full system prompt, including CLAUDE.md. The suggestion filter explicitly whitelists slash commands. When the system prompt instructs Claude to end responses with a specific trigger phrase, the suggestion generator reliably predicts /compact as the next user input, surfacing it as ghost text in the prompt entry area.
Verified working. The /compact ghost text appears after Claude emits the trigger phrase and can be accepted with a single keypress.
---
Why This Is Not Enough
- Non-deterministic. It relies on a language model predicting the next prompt, not a direct signal. The suggestion can be wrong, absent, or broken by future refactors of the suggestion system.
- Requires user interaction. Even when the suggestion appears correctly, the user must press a key. This breaks fully autonomous/headless runs: forges, multi-agent orchestration, CI pipelines.
- Not available in non-interactive sessions. The prompt suggestion UI does not exist in
--no-interactiveor piped modes.
- Implementation-dependent. This exploits an undocumented internal mechanism and could silently break in any future release.
---
Proposed Native Solution
The hooks system already proves the pattern: PreCompact and PostCompact hooks let external tools react to compaction events. The missing piece is the ability to trigger compaction rather than just react to it.
Option A: Compact tool in Claude's toolset
Add a Compact tool alongside Bash, Read, Edit, etc.:
{
"name": "Compact",
"description": "Trigger context compaction at a natural breakpoint.",
"input_schema": {
"type": "object",
"properties": {
"instructions": {
"type": "string",
"description": "Optional guidance on what context to preserve."
}
}
}
}Option B: Hook output signal
Allow hooks to return a triggerCompact signal in their JSON output, consistent with the existing additionalContext pattern:
{
"hookSpecificOutput": {
"hookEventName": "PostToolUse",
"triggerCompact": true,
"compactInstructions": "Preserve task state and file paths."
}
}Both options have prior art in the existing architecture. Option A aligns with how mcp__* tools are exposed. Option B is a natural extension of additionalContext.
---
Why choosing the moment matters
The value is not just having a compact trigger. It is Claude being able to choose the moment. Auto-compact fires at a threshold, which is often mid-reasoning. Claude-initiated compaction happens after a logical checkpoint: state persisted to files, in-flight reasoning complete, next phase not yet started. This is the difference between an autosave mid-sentence and a deliberate commit.
5 Comments
Adding a production use case that I think reinforces the case here, particularly around the 1M context model risk.
What we've built
We run a plugin/skill with a structured context management loop:
This has meaningfully extended session length and coherence in testing.
The fragile link
The compaction trigger side relies on
CLAUDE_CODE_AUTO_COMPACT_WINDOWandCLAUDE_AUTOCOMPACT_PCT_OVERRIDE. These work today but are undocumented env vars with no deprecation commitment. If they stop being honored — which becomes a more serious risk as 1M context models become standard — the default threshold lets context run to 835K+ tokens before cleanup. At that scale the coherence loss is severe, and the notes/canary system can't compensate because the trigger never came.Why this addresses the "when is it safe" concern
The implicit concern with agent-triggered compaction is: how does the agent know it's a safe moment? Our canary answers that directly. The agent only reaches for compaction after:
This isn't "agent compacts freely." It's a deliberate fallback after state is already secured. Option A (Compact tool) in the proposal above would slot directly into this pattern and close the only remaining fragile link in an otherwise resilient architecture.
The non-deterministic + requires-user-interaction failure modes you've identified are real — the CLAUDE.md workaround is clever, but it depends on the prompt suggestion path staying stable and a user at the keyboard. Your Option A (native Compact tool) and Option B (hook output signal) are the right asks for autonomous runs.
One thing that exists today for the headless/CI case at the session-file layer: cozempic's guard daemon. It watches the session JSONL, and when the file crosses a configurable threshold it terminates Claude, prunes the session (removing duplicate tool results, superseded content, large outputs already acted on — rather than summarizing), then resumes. No model signal needed, no user interaction, works in
--no-interactiveand multi-agent runs.The key difference from Option A/B: the guard fires on file-size metrics, not Claude's judgment about semantic checkpoints. Your point about choosing the moment matters — a guard at 80% is blunter than Claude deciding 'phase 2 is complete, now is the right time.' Option A would give the model that semantic agency, which is a meaningfully different thing. These aren't substitutes.
For the headless/autonomous path today:
pip install cozempic, thencozempic guard. For the richer signal-driven approach you're describing, you'd still need Anthropic to land Option A or B — but for CI pipelines and scripts that need sessions to survive past the context limit, the file-layer approach is there now.I think this would also help Anthropic as a provider, currently I basically have a dynamic workflow setup that gets triggered to implement a Ticket / Story. After that automatically the Memory is updated and I will get told to fire /compact. The Problem with this is wenn I tell claude code to go full auto and implement until stopped or lets say the next 10 Stories (actually works supprised me). Then the context grows and grows... unil autocompaction if it is reached.
The KV Cache gets evicted after every Workflowtrigger, because it takes more then the chache timeout (I think the 5 Minutes) before the Ticket is done and that is totally fine. The Problem happens not when the first Workflow comes back with beeing done, but when the 2nd and following come... This requires a full Prefill run of the up to 700k Token in the chat history. It takes forever and is computebound, so the "GPUs" are actually busy just for this one request. After compacting it is usually < 100k token... Prefill does not scale linear so it is not just a 7x increase of the time before the first token comes back
Bump.
It would be great to allow hooks to trigger compaction directly.
A particularly useful use case would be
TaskCompleted: once Claude finishes a logical task or milestone, a hook could return something liketriggerCompact: trueand compact the context before the next task starts.This would be especially valuable for fully autonomous agent workflows. An agent could work through a long sequence of tasks, compact its context at natural boundaries, and continue operating for much longer without requiring any manual intervention.
It would make truly long-running autonomous Claude Code agents much more practical and reliable.