CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: Complete Guide to Claude Code Auto-Compaction Control#

Published on March 18, 2026

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE controls when Claude Code automatically compacts (summarizes) your conversation history to free up context window space. Setting it correctly is the difference between smooth long sessions and losing critical context mid-task. This guide covers exactly how it works, the known cap bug, recommended values for every use case, and how it interacts with other compaction settings.

What CLAUDE_AUTOCOMPACT_PCT_OVERRIDE Does#

When your conversation fills the context window, Claude Code compacts older messages into a summary. This frees space but permanently loses detail. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE sets the percentage of context capacity at which this compaction triggers.

• Lower value (e.g., 50) = compaction fires earlier, more frequent but smaller summaries, more headroom
• Higher value (e.g., 90) = compaction fires later, preserves more raw context, but risks quality degradation

Without this override, Claude Code uses its internal default threshold (approximately 83%).

How to Set It#

Option 1: settings.json (Recommended)#

Add to your global settings (~/.claude/settings.json) or project settings (.claude/settings.json):

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75"
  }
}

Option 2: Shell Export#

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75
claude

Option 3: Inline#

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75 claude

Option 4: Dockerfile / CI#

ENV CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75

The value is a number between 0 and 100 representing a percentage. 75 means "compact when context reaches 75% capacity."

Note: Some older guides show decimal values like 0.8. Current versions of Claude Code accept the 0–100 integer format. If you see 0.8 in existing configs, update to 80 for clarity.

The ~83% Cap Bug#

This is the most important thing to know: you cannot raise the threshold above the internal default of approximately 83%.

What Happens#

Setting CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=95 does not trigger compaction at 95%. The internal code uses a Math.min() clamp:

effectiveThreshold = Math.min(userOverride, defaultThreshold)

This means:

• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=60 → compaction at 60% (works)
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75 → compaction at 75% (works)
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=83 → compaction at ~83% (works, matches default)
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=95 → compaction at ~83% (capped silently)

Why This Matters#

If you want to delay compaction to preserve more raw context, you can't. The env var only works in one direction: earlier compaction, not later. This is tracked in GitHub issue #31806.

The 13K Buffer#

The ~83% cap exists because Claude Code reserves a buffer of approximately 13,000 tokens for response generation. On a 200K token context window, 83% equals ~166K tokens used, leaving ~34K for the response + system overhead. This buffer prevents the model from running out of space mid-response. See GitHub issue #12004 for the technical discussion.

Practical maximum: set to 83 if you want the latest possible compaction. Going higher has no effect.

Recommended Values by Use Case#

The Sweet Spot: 75#

For most developers, 75 is the recommendation. It triggers compaction before quality degrades (the 147K–152K danger zone on 200K models), preserves enough context for multi-step reasoning, and leaves room for the response buffer.

Related Compaction Environment Variables#

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is one of several variables that control compaction behavior. Here's the full family:

Common Combinations#

Maximum context preservation (within limits):

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "83"
  }
}

Disable auto-compaction, compact manually:

{
  "env": {
    "DISABLE_AUTO_COMPACT": "1"
  }
}

Aggressive compaction for CI:

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "60"
  }
}

Warning: Setting DISABLE_COMPACT=1 disables all compaction. Your context will eventually hit the hard limit and Claude Code will fail to respond. Only use this if you're running very short sessions or managing context externally. See GitHub issue #18264 for reports of autoCompact: false being ignored.

How Compaction Affects Your Work#

When compaction fires, Claude Code:

1. Takes your conversation history up to that point
2. Summarizes it into a shorter version
3. Replaces the original messages with the summary
4. Continues the conversation with the summary as context

What's preserved: High-level task goals, file paths mentioned, key decisions made.

What's lost: Exact code snippets from earlier in the conversation, nuanced reasoning chains, specific error messages you discussed, detailed debugging context.

This is why earlier compaction (lower threshold) can actually improve quality — smaller, more frequent summaries preserve more detail than one massive compaction that tries to summarize 2 hours of work.

Troubleshooting#

"I set the value but compaction still fires at the same time"#

1. Check the format. Use integer 0–100, not decimal. 75 not 0.75.
2. Check where you set it. Project .claude/settings.json overrides global ~/.claude/settings.json. Make sure you're editing the right file.
3. Check for conflicts. If DISABLE_AUTO_COMPACT=1 is set, the percentage override is irrelevant.
4. Values above 83 are capped. See the cap bug section above.
5. Restart Claude Code. Environment variables are read at startup.

"Compaction keeps happening even with DISABLE_AUTO_COMPACT"#

This is a known issue (GitHub #18264). The autoCompact: false setting in settings.json may be ignored in some versions. Use DISABLE_AUTO_COMPACT=1 in the env block instead.

"I want compaction to never happen"#

Set DISABLE_COMPACT=1. But be aware: once you hit the context limit, Claude Code will error out. This is only practical for short, focused sessions.

FAQ#

Q: What is the default auto-compaction threshold in Claude Code?

A: The default threshold is approximately 83% of the context window capacity. On a 200K token model, compaction triggers around 166K tokens of usage. The remaining ~34K tokens are reserved as a buffer for response generation and system overhead.

Q: Can I set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE higher than the default to delay compaction?

A: No. Due to a Math.min() clamp in the internal code, values above ~83% are silently capped to the default. The env var can only trigger compaction earlier than the default, not later. This is tracked in GitHub issue #31806.

Q: What value should I use for CLAUDE_AUTOCOMPACT_PCT_OVERRIDE?

A: 75 is the recommended starting point for most development work. It triggers compaction before the quality degradation zone (~147K tokens on 200K models) while preserving enough context for multi-step reasoning. Adjust down to 60–70 for short tasks or debugging, up to 80–83 for complex multi-file work.

Q: Does CLAUDE_AUTOCOMPACT_PCT_OVERRIDE accept decimal values like 0.8?

A: Current versions accept values in the 0–100 range as a percentage. Use 80 rather than 0.8. Some older documentation may show decimal format, but integer format is the standard.

Q: How do I completely disable auto-compaction?

A: Set DISABLE_AUTO_COMPACT=1 in your settings.json env block. This disables automatic compaction while still allowing manual /compact commands. To disable all compaction including manual, use DISABLE_COMPACT=1 — but be cautious, as your session will eventually hit the hard context limit.

Q: Does CLAUDE_AUTOCOMPACT_PCT_OVERRIDE work with the 1M context window?

A: Yes, it works as a percentage of whatever context window size is active. If you're on a 1M token context window, setting it to 75 means compaction triggers at approximately 750K tokens.

Related: Context Window Management Guide | 500+ Environment Variables Reference | Debugging Claude Code Issues | Claude Code Productivity Tips