[DOCS] Auto-compaction docs omit thrash-loop stop condition

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/how-claude-code-works

Section/Topic

"The context window" -> "When context fills up", plus the troubleshooting guidance for repeated auto-compaction failures

Current Documentation

The docs currently say:

Claude's context window holds your conversation history, file contents, command outputs, CLAUDE.md, auto memory, loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run /context to see what's using space. Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history.

Another user-facing page says:

When context fills up, Claude automatically summarizes the conversation and continues working. You can also type /compact to trigger summarization earlier and free up context space.

The troubleshooting page currently says only:

1. Use /compact regularly to reduce context size 2. Close and restart Claude Code between major tasks 3. Consider adding large build directories to your .gitignore file

What's Wrong or Missing?

Changelog v2.1.89 says:

Fixed autocompact thrash loop — now detects when context refills to the limit immediately after compacting three times in a row and stops with an actionable error instead of burning API calls

The published docs still describe normal auto-compaction only. They do not explain the new stop condition where compaction immediately refills the context limit three times in a row and Claude stops auto-compacting instead of continuing to retry.

That leaves out the part users need when a long session hits this state:

• why auto-compaction stopped,
• what the actionable error means,
• how this differs from ordinary compaction,
• where to look for recovery steps.

Suggested Improvement

Add a short note to "When context fills up" explaining that if compaction immediately refills the context limit three times in a row, Claude Code stops auto-compacting and surfaces an actionable error instead of looping.

The docs should then point users to manual recovery options that are already documented elsewhere, such as running /compact with focused instructions, clearing the session with /clear if the old context is no longer needed, or moving unrelated work into a fresh session/subagent.

Also add a troubleshooting entry for repeated compaction/refill loops so users can recognize this failure mode and understand why Claude stopped compacting automatically.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/how-claude-code-works | Primary explanation of what happens when context fills up |
| https://code.claude.com/docs/en/desktop | Says Claude automatically summarizes the conversation and continues working |
| https://code.claude.com/docs/en/best-practices | Explains what happens when auto compaction triggers during long sessions |
| https://code.claude.com/docs/en/sub-agents | Says subagents use the same auto-compaction logic as the main conversation |
| https://code.claude.com/docs/en/troubleshooting | No troubleshooting entry for repeated compaction refills or the resulting error |

Total scope: 5 pages affected

Source: Changelog v2.1.89

Exact changelog entry: Fixed autocompact thrash loop — now detects when context refills to the limit immediately after compacting three times in a row and stops with an actionable error instead of burning API calls