[DOCS] No documentation for disabling auto-compaction

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

Auto-compaction configuration

Current Documentation

The Settings page documents CLAUDE_AUTOCOMPACT_PCT_OVERRIDE for adjusting when auto-compaction triggers (threshold 1–100%, default 95%). The Costs page explains what auto-compaction does and how to use /compact manually.

Neither page documents how to disable auto-compaction entirely.

What's Wrong or Missing?

There is no official documentation for disabling auto-compaction. Users who want to disable it must discover methods through community workarounds in GitHub Issues (#6689, #2222, #2283, #2391).

Community-discovered methods include:

1. /config → toggle "Auto-compact" (per-session, doesn't persist across restarts in some environments)
2. claude config set -g autoCompactEnabled false (writes to ~/.claude.json)
3. Editing ~/.claude.json directly
4. DISABLE_AUTO_COMPACT=true environment variable

The lack of documentation leads to a predictable user mistake: writing "autoCompactEnabled": false in ~/.claude/settings.json. This seems like the natural place — it's the documented settings file with a published JSON Schema. However:

• autoCompactEnabled is not defined in the settings.json schema
• The setting is silently ignored (no error, no warning)
• The actual storage location is ~/.claude.json (a separate app state file)

Suggested Improvement

1. Document the supported ways to disable auto-compaction on the Settings page, alongside CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
2. Clarify the relationship between ~/.claude/settings.json (user settings) and ~/.claude.json (app state) — currently undocumented

Impact

High - Prevents users from using a feature

Additional Context

• This is especially painful in containerized environments where ~/.claude.json is ephemeral but ~/.claude/settings.json is mounted from the host
• Related: #6689 (feature request for --no-auto-compact CLI flag)
• No official response has been given on any of the related Issues

---

✍️ Author: Claude Code (Reizan Container) with @carrotRakko