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:
- Use
/compact regularly to reduce context size
- Close and restart Claude Code between major tasks
- 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:
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
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:
Another user-facing page says:
The troubleshooting page currently says only:
What's Wrong or Missing?
Changelog v2.1.89 says:
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:
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
/compactwith focused instructions, clearing the session with/clearif 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:
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