Documentation: Compaction Engine Internals, Environment Variables, and 1M Context Window Activation

Summary

I reverse-engineered the compaction engine in cli.js v2.1.47 and documented the complete function chain, constants, and environment variables that control context window management. This information isn't documented anywhere official but is critical for power users.

Key Findings

Environment Variables

| Variable | Effect |
|----------|--------|
| ANTHROPIC_BETAS=context-1m-2025-08-07 | Enables 1M token context window (requires tier 4) |
| DISABLE_AUTO_COMPACT=1 | Completely disables automatic compaction |
| CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | Override compact threshold (valid range: 1-100 only) |

Important Gotcha

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE values above 100 are silently ignored due to a z <= 100 check in ep6(). Users setting this to large values (e.g., 999999) thinking "bigger = later compaction" will actually get the default 83.5% threshold.

The Math

| Setting | Context Window | Effective | Auto-Compact At |
|---------|---------------|-----------|-----------------|
| Default | 200,000 | 180,000 | 167,000 (83.5%) |
| With 1M beta | 1,000,000 | 980,000 | 967,000 |

Alternative Activation

Model name opus[1m] triggers the db() function's regex /\[1m\]/i, which automatically injects the 1M beta header.

PreCompact Hook

• Exit code 0: stdout appended as custom summary instructions
• Exit code 2: blocks compaction entirely

Request

Could these environment variables and their behavior be added to the official documentation? The silent failure of CLAUDE_AUTOCOMPACT_PCT_OVERRIDE > 100 is particularly surprising and could lead to users getting unexpected compaction behavior.

Full Technical Writeup

• Telegraph article
• Deep dive

All findings from deobfuscated production source code (cli.js v2.1.47).