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

1. 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.

1. 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.

1. Not available in non-interactive sessions. The prompt suggestion UI does not exist in --no-interactive or piped modes.

1. 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.