[FEATURE] Configurable Auto-Compact Threshold in VS Code Extension

[jimmy058910]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

The Claude Code VS Code extension auto-triggers /compact at approximately 35% context remaining, while the CLI version operates down to ~1-5% before compaction. This 30-34% difference forces frequent, premature context loss during complex development tasks.

Current Impact:

• Extension users lose context after reading only 6-7 files in a 12-file refactoring task
• CLI users can read all 12 files plus their relationships in a single context window
• Result: Extension requires 2-3 compaction cycles with 20+ redundant file re-reads vs CLI's single pass

Real-World Example:

Task: Refactor DDD architecture across 12 backend files

Extension (35% threshold):
1. Read files 1-6 → Auto-compact at 35%
2. Lose context of files 1-3
3. Re-read files 1-3 + read files 7-9 → Auto-compact again
4. Total: 3-4 compaction cycles, 20+ redundant file reads

CLI (5% threshold):
1. Read all 12 files → 8% context remaining
2. Retain complete architectural view
3. Total: 1 compaction, 0 redundant reads

This creates a 60-70% efficiency gap between extension and CLI for power users working on complex, multi-file tasks.

Proposed Solution

Add a user-configurable setting in settings.json to control auto-compact threshold:

Minimum Viable Product (MVP)

{
  "claudeCode.autoCompactThreshold": 0.35  // Default: 0.35 (35%), Range: 0.01-0.50
}

Enhanced Version (Future)

{
  "claudeCode.contextManagement": {
    "autoCompactThreshold": 0.05,    // When to auto-compact (1-50%)
    "compactBehavior": "auto",       // "auto" | "prompt" | "manual"
    "warningThreshold": 0.10         // Show warning before auto-compact
  }
}

Configuration Options:

• Default (35%): Current behavior - safe for all users, maintains stability
• Aggressive (5%): Match CLI behavior - for power users, requires monitoring
• Custom (10-20%): Balanced - moderate risk, better context utilization

Safety Mechanisms:

• Minimum threshold: 1% (prevents values below safe limit)
• Force-compact at 0.5%: Regardless of user setting (prevents extension crash)
• Warning UI: Notification when <10% context remains

Alternative Solutions

Alternative Solutions

❌ Alternative 1: Always Use 5% Threshold

Rejected - Too risky for non-technical users, could cause extension crashes and poor user experience for general audience.

❌ Alternative 2: Automatic Detection Based on Codebase Size

Rejected - Requires complex heuristics, unpredictable behavior, difficult to debug when issues occur.

❌ Alternative 3: Separate "Power User Mode" Toggle

Rejected - Less granular control, doesn't address users who want middle-ground (10-20% threshold).

✅ Alternative 4: User-Configurable Threshold (Proposed)

Selected - Gives users full control, backward compatible (default unchanged), opt-in risk model, aligns with VS Code's configuration philosophy.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

Use Case Examples

Use Case 1: Multi-Layer Feature Implementation

Scenario: Implementing live match streaming across Unity → Backend → Frontend (15+ files)

Current Experience (35%):

• Read Unity layer (5 files) → Auto-compact
• Lose Unity context when reading Backend layer
• Must re-read Unity files when debugging integration
• Total: 3-4 compaction cycles

With 5% Threshold:

• Read all 3 layers in single context window
• Maintain cross-stack relationships throughout implementation
• Immediate integration debugging without re-reading

Benefit: 70% reduction in redundant file reads, faster integration debugging

---

Use Case 2: Architectural Refactoring

Scenario: Converting monolithic backend to Domain-Driven Design (12+ files)

Current Experience (35%):

• Can only analyze 6-7 files before compaction
• Lose architectural context mid-refactoring
• Difficult to maintain consistency across layers

With 5% Threshold:

• Read entire architecture in one pass
• Understand all relationships before making changes
• Consistent refactoring decisions across all files

Benefit: Complete architectural visibility, fewer consistency errors

---

Use Case 3: Documentation + Implementation

Scenario: Reading 5 documentation files before implementing complex feature

Current Experience (35%):

• Read 3-4 docs → Auto-compact
• Lose documentation context during implementation
• Must re-read docs for clarification

With 5% Threshold:

• Read all docs + keep in context during implementation
• Reference design decisions without re-reading

Benefit: Faster implementation, better adherence to specifications

Additional Context

Why Extension Differs from CLI

CLI (1-5% threshold):

• Simpler state management (no IDE integration)
• Technical users who understand risks
• Easier recovery from context overflow

Extension (35% threshold):

• Complex IDE integration (file watchers, diagnostics, state)
• Diverse user base (including non-technical users)
• Stability is critical for extension reliability

Why Configurable is Best:

• Maintains 35% default for safety/stability
• Allows power users to opt-in to CLI-level efficiency
• Backward compatible (no breaking changes)

---

Technical Details

Context Window Math:

Claude Sonnet 4.5: 200,000 total tokens
Extension reserves: ~20,000 tokens (system prompts, IDE state)
Available: ~180,000 tokens

Current (35%): 180,000 * 0.35 = 63,000 tokens remaining → compact
Proposed (5%): 180,000 * 0.05 =  9,000 tokens remaining → compact

Delta: 54,000 tokens (~27 additional 2KB files)

Impact Analysis:

• Low-Risk Users (keep default 35%): Zero impact, backward compatible
• Power Users (opt-in to 5%): 60-70% fewer redundant reads, complete architectural visibility
• Context Overflow Risk: <0.1% increase (with safety guards in place)

---

Current Workarounds

1. Manual Compaction:

• Monitor context percentage constantly
• Type /compact manually before 35% threshold
• Limitation: Requires constant vigilance, interrupts workflow

2. Use CLI for Complex Tasks:

• Switch to CLI for architectural work
• Return to extension for editing
• Limitation: Context switching overhead, loses IDE integration benefits

3. Break Tasks into Smaller Chunks:

• Artificially limit scope of analysis
• Work in 5-6 file batches
• Limitation: Lose architectural coherence, higher risk of inconsistencies

---

Similar Features in Other Tools

• Cursor IDE: Configurable context window management, user-defined compaction thresholds
• Continue.dev: Manual compaction mode, context usage visualization
• Windsurf: Adjustable context preservation settings

---

Implementation Effort Estimate

Low (MVP - Single Setting):

• Add claudeCode.autoCompactThreshold number field to settings schema
• Replace hardcoded 0.35 with config value (with validation)
• Update documentation
• Estimated Effort: 1-2 days

Medium (Enhanced Version):

• Add structured contextManagement object
• Implement compactBehavior options (auto/prompt/manual)
• Add warning UI at threshold
• Comprehensive testing
• Estimated Effort: 3-5 days

---

Success Metrics

If Implemented:

1. Adoption: 15-20% of active users customize threshold
2. Efficiency: Average context utilization increases from 65% to 85-90% for opted-in users
3. Stability: Context overflow rate remains <0.1% (within acceptable bounds)
4. Satisfaction: 50%+ reduction in "lost context" user feedback

---

Environment:

• VS Code Version: 1.96.2
• Claude Code Extension Version: Latest
• OS: Windows 11 (also affects macOS/Linux)
• Willing to Beta Test: ✅ Yes

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[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.