How to Configure Claude Code Auto-Compact Settings with Environment Variables

Mar 21, 2026

Problem

Claude Code automatically compacts conversation history when context approaches capacity. But the default settings didn’t work well for me. Sometimes context filled up too quickly during complex tasks. Other times, compaction happened at inconvenient moments, losing important context.

I needed more control over when and how auto-compact triggered.

What I tried first

I looked for settings in the usual places:

Configuration files in ~/.claude/
Command-line flags
Documentation

I found mentions of auto-compact but no clear instructions on how to configure it. The default behavior was opaque. I couldn’t predict when compaction would occur.

The solution

I discovered that Claude Code supports two environment variables for controlling auto-compact:

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE - Percentage threshold for triggering auto-compact
CLAUDE_CODE_AUTO_COMPACT_WINDOW - Reduces the effective token window size

These settings give you two different approaches to managing context.

Method 1: Compact at percentage of context

This approach triggers auto-compact when your conversation reaches a specific percentage of the model’s context window.

Let’s say you’re using Claude with a 200k token context window. By default, auto-compact might trigger at 90% capacity (180k tokens). But if you want to trigger it earlier, you can set:

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=47

With this setting on a 200k model:

Auto-compact triggers at approximately 94k tokens (47% of 200k)
Compaction happens earlier, preventing context from getting too full
You get more predictable behavior in long sessions

I tested this with a 200k model:

Before: Auto-compact at ~180k tokens (90% of 200k)
After setting CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=47:
  Auto-compact at ~94k tokens (47% of 200k)

Why would you want this? If you’ve experienced issues when context gets too full (similar to problems in other AI tools), triggering compaction earlier can improve reliability.

Method 2: Reduce token window

This approach first reduces the effective context window size, then applies percentage-based compaction.

export CLAUDE_CODE_AUTO_COMPACT_WINDOW=100000
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=95

With these settings on a 200k model:

Claude treats the context window as 100k tokens (not 200k)
At 95% of 100k, auto-compact triggers at 95k tokens
You get predictable, absolute token limits

The difference from Method 1:

Method 1 (percentage only):
  200k window, trigger at 47% = 94k tokens

Method 2 (window + percentage):
  100k effective window, trigger at 95% = 95k tokens

Both methods trigger around the same point, but Method 2 gives you more control over the absolute number of tokens.

When to use each method

I use Method 1 when:

I want to trigger compaction earlier in the context window
I’m working on tasks that don’t need full context
I want simpler configuration (one variable)

I use Method 2 when:

I need predictable, absolute token limits
I’m debugging context-related issues
I want to test behavior at specific token counts
I’m working with models of different context sizes and want consistent compaction points

How to set these variables

You can set them in your shell configuration:

# Method 1: Percentage only
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=47

# Method 2: Window + percentage
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=100000
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=95

Or set them for a single session:

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=47 claude

Or set them before running Claude Code:

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=47
claude

Common mistakes I made

Mistake 1: Setting percentage too low

I initially set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=10, thinking more compaction would be better.

Reality: This triggered compaction too frequently. I lost useful context and wasted tokens on repeated compaction operations. A value between 40-70% works better for most use cases.

Mistake 2: Using both variables incorrectly

I set both variables thinking they would combine:

# What I tried (incorrect expectation)
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=100000
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=47

I expected: 47% of 100k = 47k tokens.

Reality: The percentage applies to the original window, not the reduced window. If you want 47% of a 100k effective window, set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=47 and CLAUDE_CODE_AUTO_COMPACT_WINDOW=100000 together, but test to verify the behavior matches your expectations.

Mistake 3: Not restarting Claude Code after changes

I edited my shell config but didn’t restart Claude Code.

Reality: Environment variables only apply to new sessions. After changing settings:

# Apply changes
source ~/.zshrc

# Then start Claude Code
claude

Mistake 4: Setting window size higher than model capacity

I set CLAUDE_CODE_AUTO_COMPACT_WINDOW=300000 on a 200k model.

Reality: This setting only reduces the effective window. It cannot increase capacity beyond the model’s limit. Setting it higher than the actual limit has no effect.

Why this matters

Configuring auto-compact settings improves Claude Code’s reliability during long conversations. Users working on complex, multi-file tasks or extended coding sessions benefit from predictable context management.

Without these settings:

Context fills unpredictably
Compaction triggers at unknown points
Context loss can break your workflow

With these settings:

Predictable compaction timing
Better control over context lifecycle
Fewer surprises during long sessions

Summary

In this post, I showed how to configure Claude Code’s auto-compact behavior using two environment variables. The key points are:

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE controls when compaction triggers as a percentage
CLAUDE_CODE_AUTO_COMPACT_WINDOW reduces the effective token window
Use Method 1 for simpler percentage-based control
Use Method 2 for predictable absolute token limits
Test different values to find what works for your use case

These settings are particularly useful if you’ve experienced context-related issues similar to those encountered in other AI tools. By controlling when compaction occurs, you can make Claude Code’s behavior more predictable during extended sessions.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion on Auto-Compact Settings

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!