[DOCS] No documentation for disabling auto-compaction

[carrotRakko]

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: [FEATURE] Add --no-auto-compact command switch to Disable the auto-compaction #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

[github-actions]

Found 3 possible duplicate issues:

1. [DOCS] Add warning that mcpServers in settings.json / settings.local.json is silently ignored #24477
2. [DOCS] CLI Reference lacks guidance on environment-variable-only configuration options #20244
3. [Feature Request] Document configuration file structure and directory hierarchy rationale #24005

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[carrotRakko]

These are not duplicates. Here's why:

Issue	Problem	Scope
#24477	mcpServers in settings.json is silently ignored	MCP server configuration
#20244	CLI Reference lacks env-var-only config guidance	CLI documentation coverage
#24005	Config file structure rationale undocumented	General config architecture
#24589 (this)	No documented way to disable auto-compaction	Auto-compaction setting

Key distinctions:

• [DOCS] Add warning that mcpServers in settings.json / settings.local.json is silently ignored #24477: Same structural problem (settings.json vs .claude.json confusion), but for MCP servers, not auto-compaction. Related, not duplicate.
• [DOCS] CLI Reference lacks guidance on environment-variable-only configuration options #20244: Broad request for documenting env-var-only options in the CLI Reference. This issue is specifically about auto-compaction having no documented disable method anywhere — not just in the CLI Reference.
• [Feature Request] Document configuration file structure and directory hierarchy rationale #24005: General request for config file hierarchy documentation. This issue reports a concrete user-facing problem: users write "autoCompactEnabled": false in settings.json (the documented settings file), it's silently ignored, and the actual method (~/.claude.json) is undocumented.

These issues do share a root cause — the .claude.json vs settings.json split is undocumented — but each describes a different user-facing problem. Fixing any one of them would not resolve the others.

---

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

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.