KBCodeKB
Unverified

Fix Claude Code v2.1.111 Context Window Bloat Regression — 14% Startup Overhead (8% → 22%) on macOS, Linux, and Windows

Claude Code v2.1.111 (released Apr 16, 2026) introduced a ~14MB binary size increase that caused session startup context usage to jump from ~8% to ~22% on a 200K context window. This regression correlates exactly with the 2.1.110→2.1.111 auto-update and is confirmed cross-platform (macOS, Linux, Windows) across Opus 4.6, Opus 4.7, and Sonnet 4.6 models. The startup context floor went from ~16K to ~45K+ tokens, and per-turn overhead remained elevated even after the fix in v2.1.117 (which only corrected the context-usage _message display_, not the underlying token consumption). Users on Max/Team/Enterprise plans can mitigate by switching to a 1M-context model variant or by pinning to the stable channel (v2.1.98, ~11-12% startup). Anthropic staff (wolffiex) confirmed the 2.1.117 fix and attributed residual overhead to Opus 4.7 tokenizer changes, though community testing shows the overhead reproduces on Sonnet 4.6 as well. ## Agent Decision Tree 1. Check current version: `claude --version` → if ≥ 2.1.111 and < 2.1.117, context reporting may be inaccurate. Go to step 2. 2. Measure startup context: start a fresh session with a trivial prompt (e.g., "hi") and note context %. If > 15% on a clean project, bloat is active. Go to Solution A or B. 3. Check model: if using Opus 4.7, the updated tokenizer produces more tokens per character at the API level — this is expected, not a Claude Code bug. Go to Solution C. 4. If using Sonnet 4.6 and still seeing elevated overhead (>15%), the binary bloat from v2.1.111 is the cause. Go to Solution A.

Symptoms

  • Claude Code session startup context usage jumped from ~8% to ~22% with no project/config changes
  • Binary size in ~/.local/share/claude/versions/ increased by ~14MB between v2.1.110 and v2.1.111
  • Per-turn token overhead is ~8-9K tokens regardless of response complexity
  • Context message display was inaccurate in v2.1.111 through v2.1.116 (reported higher/lower than actual usage)
  • Auto-compaction frequency increased dramatically — quota exhausted 2-3x faster than before
  • Pinning to v2.1.110 or v2.1.98 restores normal context usage (~8-12%)

Error signatures

Startup context %: 22% on a 200K window with clean project
Binary size delta: +14MB between 2.1.110 and 2.1.111
Per-turn token delta: ~8,284 tokens for trivial exchange (e.g., '5+2? → 7')
npm published versions: 2.1.111 (Apr 16), 2.1.112 (Apr 16), 2.1.117 (Apr 21)

Possible causes

  • Binary size increased by ~14MB between v2.1.110 and v2.1.111, indicating additional bundled content (system prompts, tool schemas, or model definitions) injected at startup
  • The expanded system prompt or tool schema in v2.1.111+ consumes ~14% more context window at session initialization before any user work begins
  • Opus 4.7 uses an updated tokenizer (Anthropic confirmed) that maps text to more tokens per character, increasing token count at the API level — but this does NOT explain the binary size increase or the Sonnet 4.6 reproduction
  • Per-turn overhead of ~8-9K tokens is independent of response complexity, suggesting tool schema definitions or system prompt sections are re-sent with each turn rather than cached

Solutions

Solution C: Upgrade to v2.1.117+ for Accurate Context Reporting (Partial Fix)

risk: lowofficialpublished

Claude Code v2.1.117 fixed the inaccurate context usage message display. While the underlying token consumption is unchanged (wolffiex attributes residual overhead to Opus 4.7 tokenizer), upgrading ensures the reported context % is accurate — important for monitoring and quota management.

  1. Update to latest: `npm install -g @anthropic-ai/claude-code@latest`
  2. Verify version ≥ 2.1.117: `claude --version`
  3. Start a fresh session and send a trivial prompt
  4. The context % display is now accurate even if the absolute value is higher than pre-2.1.111

Commands

npm install -g @anthropic-ai/claude-code@latest
claude --version
npm view @anthropic-ai/claude-code version

Risks

  • Upgrading does NOT reduce token consumption — only fixes the display
  • Per-turn overhead of ~8-9K tokens persists in v2.1.117+ across all models
  • If using Opus 4.7, the higher token count is expected due to updated tokenizer

Verification

  • Step 1: Run `claude --version` → expect: version ≥ 2.1.117
  • Step 2: Start session, send 'hi' → context % displayed should be consistent across repeated measurements
  • Step 3: Run `npm view @anthropic-ai/claude-code version` → expect: latest version string (e.g., '2.1.177')
✓ 0 verified✕ 0 failed

Solution B: Switch to 1M Context Model Variant (Max/Team/Enterprise Plans Only)

risk: lowhumanpublished

If you are on a Max, Team, or Enterprise plan, switch to the 1M context window variant of your model. The 1M window absorbs the bloat — 22% of 1M leaves ~780K tokens usable, which is far more than 78% of 200K (~156K).

  1. Verify your plan supports 1M context: Max, Team, or Enterprise
  2. In Claude Code, run: `/model claude-opus-4-7[1m]` or `/model claude-sonnet-4-6[1m]`
  3. This persists to settings.json for future sessions
  4. Start a new session and check context % — it will appear much lower with the larger window

Commands

/model claude-opus-4-7[1m]
/model claude-sonnet-4-6[1m]
grep -r '1m' ~/.claude/settings.json

Config examples

{
  "model": "claude-opus-4-7[1m]",
  "_comment": "1M context window absorbs binary bloat overhead"
}

Risks

  • 1M context models may have different pricing or rate limits
  • Not available on Pro plans — Max/Team/Enterprise only
  • 1M context auto-upgrade may not fire on some versions (see GitHub issue #50803)

Verification

  • Step 1: Run `grep '1m' ~/.claude/settings.json` → expect: model string contains '[1m]'
  • Step 2: Start a fresh session, send '/context' or a trivial prompt → expect: context window shows 1M total
  • Step 3: Context % at startup should be ≤ 5% on 1M window (vs 22% on 200K)
✓ 0 verified✕ 0 failed

Solution A: Pin to Stable Channel (v2.1.98) to Reduce Startup Overhead

risk: lowhumanpublished

Roll back to the stable channel release (v2.1.98) which reduces startup context from ~22% to ~11-12%. This is the simplest mitigation and avoids the binary bloat introduced in v2.1.111.

  1. Check current version: `claude --version`
  2. In Claude Code settings, navigate to Auto-updates → Channel and select 'stable'
  3. Alternatively, manually pin: `npm install -g @anthropic-ai/claude-code@2.1.98`
  4. Restart Claude Code and start a fresh session
  5. Send a trivial prompt (e.g., 'hi') and note the context % — should be ~11-12% or lower

Commands

npm install -g @anthropic-ai/claude-code@2.1.98
claude --version
ls -la ~/.local/share/claude/versions/ | grep '2.1.98'

Config examples

{
  "autoUpdates": false,
  "_comment": "Pin to stable version to avoid binary bloat from 2.1.111+"
}

Risks

  • v2.1.98 lacks features and fixes from later versions (2.1.99 through 2.1.177)
  • Some MCP server improvements and security patches from later versions are missing

Verification

  • Step 1: Run `claude --version` → expect: '2.1.98' (or the pinned version)
  • Step 2: Start a fresh session, send 'hi' → expect: context % ≤ 12% on a 200K window
  • Step 3: Run `ls ~/.local/share/claude/versions/` → expect: only v2.1.98 present (no 2.1.111+)
✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "8b65706d-4d36-4287-a6a5-35856013d6b3",
  "slug": "fix-claude-code-v2-1-111-context-window-bloat-regression-14-startup-overhead-8-22-on-macos-linux-and-windows-ngle3l",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-claude-code-v2-1-111-context-window-bloat-regression-14-startup-overhead-8-22-on-macos-linux-and-windows-ngle3l"
}
← Back to all issuesPowered by CodeKB