SuperClaude/Framework-Hooks/docs/Hooks/pre_compact.md

pre_compact Hook Technical Documentation

Purpose

The pre_compact hook implements token optimization before context compaction in Claude Code. It analyzes content for compression opportunities, applies selective compression strategies, and maintains quality preservation targets while reducing token usage.

Core Implementation: Implements MODE_Token_Efficiency.md compression algorithms with selective content classification, symbol systems, and quality-gated compression with a target execution time of <150ms.

Execution Context

The pre_compact hook runs before context compaction in Claude Code. According to settings.json, it has a 15-second timeout and executes via: python3 ~/.claude/hooks/pre_compact.py

Actual Execution Flow:

1. Receives compaction request from Claude Code via stdin (JSON)
2. Initializes PreCompactHook class with compression engine and shared modules
3. Processes request through process_pre_compact() method
4. Analyzes content characteristics and determines compression strategy
5. Outputs compression configuration via stdout (JSON)
6. Falls back gracefully on errors with no compression applied

Performance Target

Performance Target: <150ms execution time

The hook operates within strict performance constraints to ensure real-time compression decisions:

Performance Benchmarks

• Target Execution Time: 150ms maximum
• Typical Performance: 50-100ms for standard content
• Efficiency Metric: 100 characters per millisecond processing rate
• Resource Overhead: <5% additional memory usage during compression

Performance Monitoring

performance_metrics = {
    'compression_time_ms': execution_time,
    'target_met': execution_time < 150,
    'efficiency_score': chars_per_ms / 100,
    'processing_rate': content_length / execution_time
}

Optimization Strategies

• Parallel Content Analysis: Concurrent processing of content sections
• Intelligent Caching: Reuse compression results for similar content patterns
• Early Exit Strategies: Skip compression for framework content immediately
• Selective Processing: Apply compression only where beneficial

Compression Levels

5-Level Compression Strategy providing adaptive optimization based on resource constraints and content characteristics:

Level 1: Minimal (0-40% compression)

compression_level: minimal
symbol_systems: false
abbreviation_systems: false
structural_optimization: false
quality_threshold: 0.98
use_cases:
  - user_content
  - low_resource_usage
  - high_quality_required

Application: User project files, documentation, source code requiring high fidelity preservation.

Level 2: Efficient (40-70% compression)

compression_level: efficient
symbol_systems: true
abbreviation_systems: false
structural_optimization: true
quality_threshold: 0.95
use_cases:
  - moderate_resource_usage
  - balanced_efficiency

Application: Session metadata, checkpoint data, working artifacts with acceptable optimization trade-offs.

Level 3: Compressed (70-85% compression)

compression_level: compressed
symbol_systems: true
abbreviation_systems: true
structural_optimization: true
quality_threshold: 0.90
use_cases:
  - high_resource_usage
  - user_requests_brevity

Application: Analysis results, cached data, temporary working content with aggressive optimization.

Level 4: Critical (85-95% compression)

compression_level: critical
symbol_systems: true
abbreviation_systems: true
structural_optimization: true
advanced_techniques: true
quality_threshold: 0.85
use_cases:
  - resource_constraints
  - emergency_compression

Application: Emergency resource situations, historical session data, highly repetitive content.

Level 5: Emergency (95%+ compression)

compression_level: emergency
symbol_systems: true
abbreviation_systems: true
structural_optimization: true
advanced_techniques: true
aggressive_optimization: true
quality_threshold: 0.80
use_cases:
  - critical_resource_constraints
  - emergency_situations

Application: Critical resource exhaustion scenarios with maximum token conservation priority.

Selective Compression

Framework exclusion and content classification ensuring optimal compression strategies based on content type and preservation requirements:

Content Classification System

Framework Content (0% compression)

framework_exclusions:
  patterns:
    - "~/.claude/"
    - ".claude/"
    - "SuperClaude/*"
    - "CLAUDE.md"
    - "FLAGS.md"
    - "PRINCIPLES.md"
    - "ORCHESTRATOR.md"
    - "MCP_*.md"
    - "MODE_*.md"
    - "SESSION_LIFECYCLE.md"
  compression_level: "preserve"
  reasoning: "Framework content must be preserved for proper operation"

Protection Strategy: Complete exclusion from all compression algorithms with immediate early exit upon framework content detection.

User Content Preservation (Minimal compression)

user_content_preservation:
  patterns:
    - "project_files"
    - "user_documentation"
    - "source_code"
    - "configuration_files"
    - "custom_content"
  compression_level: "minimal"
  reasoning: "User content requires high fidelity preservation"

Protection Strategy: Light compression with whitespace optimization only, preserving semantic accuracy and technical correctness.

Session Data Optimization (Efficient compression)

session_data_optimization:
  patterns:
    - "session_metadata"
    - "checkpoint_data"
    - "cache_content"
    - "working_artifacts"
    - "analysis_results"
  compression_level: "efficient"
  reasoning: "Session data can be compressed while maintaining utility"

Optimization Strategy: Symbol systems and structural optimization applied with 95% quality preservation target.

Content Detection Algorithm

def _analyze_content_sources(self, content: str, metadata: dict) -> Tuple[float, float]:
    """Analyze ratio of framework vs user content."""
    framework_indicators = [
        'SuperClaude', 'CLAUDE.md', 'FLAGS.md', 'PRINCIPLES.md',
        'ORCHESTRATOR.md', 'MCP_', 'MODE_', 'SESSION_LIFECYCLE'
    ]
    
    user_indicators = [
        'project_files', 'user_documentation', 'source_code',
        'configuration_files', 'custom_content'
    ]

Symbol Systems

Symbol systems replace verbose text with standardized symbols for efficient communication while preserving semantic meaning:

Core Logic & Flow Symbols

Symbol	Meaning	Example Usage
→	leads to, implies	auth.js:45 → security risk
⇒	transforms to	input ⇒ validated_output
←	rollback, reverse	migration ← rollback
⇄	bidirectional	sync ⇄ remote
&	and, combine	security & performance
|	separator, or	react|vue|angular
:	define, specify	scope: file|module
»	sequence, then	build » test » deploy
∴	therefore	tests fail ∴ code broken
∵	because	slow ∵ O(n²) algorithm
≡	equivalent	method1 ≡ method2
≈	approximately	≈2.5K tokens
≠	not equal	actual ≠ expected

Status & Progress Symbols

Symbol	Meaning	Context
✅	completed, passed	Task completion, validation success
❌	failed, error	Operation failure, validation error
⚠️	warning	Non-critical issues, attention required
ℹ️	information	Informational messages, context
🔄	in progress	Active operations, processing
⏳	waiting, pending	Queued operations, dependencies
🚨	critical, urgent	High-priority issues, immediate action
🎯	target, goal	Objectives, milestones
📊	metrics, data	Performance data, analytics
💡	insight, learning	Discoveries, optimizations

Technical Domain Symbols

Symbol	Domain	Usage Context
⚡	Performance	Speed optimization, efficiency
🔍	Analysis	Investigation, examination
🔧	Configuration	Setup, tool configuration
🛡️	Security	Protection, vulnerability analysis
📦	Deployment	Packaging, distribution
🎨	Design	UI/UX, frontend development
🌐	Network	Web services, connectivity
📱	Mobile	Responsive design, mobile apps
🏗️	Architecture	System structure, design patterns
🧩	Components	Modular design, composability

Symbol System Implementation

symbol_systems = {
    'core_logic_flow': {
        'enabled': True,
        'mappings': {
            'leads to': '→',
            'transforms to': '⇒',
            'therefore': '∴',
            'because': '∵'
        }
    },
    'status_progress': {
        'enabled': True,
        'mappings': {
            'completed': '✅',
            'failed': '❌',
            'warning': '⚠️',
            'in progress': '🔄'
        }
    }
}

Abbreviation Systems

Technical abbreviations for efficiency providing domain-specific shorthand while maintaining clarity and context:

System & Architecture Abbreviations

Full Term	Abbreviation	Context
configuration	cfg	System settings, setup files
settings	cfg	Configuration parameters
implementation	impl	Code structure, algorithms
code structure	impl	Software architecture
architecture	arch	System design, patterns
system design	arch	Architectural decisions
performance	perf	Optimization, benchmarks
optimization	perf	Efficiency improvements
operations	ops	Deployment, DevOps
deployment	ops	Release processes
environment	env	Runtime context, settings
runtime context	env	Execution environment

Development Process Abbreviations

Full Term	Abbreviation	Context
requirements	req	Project specifications
dependencies	deps	Package management
packages	deps	Library dependencies
validation	val	Testing, verification
verification	val	Quality assurance
testing	test	Quality validation
quality assurance	test	Testing processes
documentation	docs	Technical writing
guides	docs	User documentation
standards	std	Coding conventions
conventions	std	Style guidelines

Quality & Analysis Abbreviations

Full Term	Abbreviation	Context
quality	qual	Code quality, maintainability
maintainability	qual	Long-term code health
security	sec	Safety measures, vulnerabilities
safety measures	sec	Security protocols
error	err	Exception handling
exception handling	err	Error management
recovery	rec	Resilience, fault tolerance
resilience	rec	System robustness
severity	sev	Priority levels, criticality
priority level	sev	Issue classification
optimization	opt	Performance improvements
improvement	opt	Enhancement strategies

Abbreviation System Implementation

abbreviation_systems = {
    'system_architecture': {
        'enabled': True,
        'mappings': {
            'configuration': 'cfg',
            'implementation': 'impl',
            'architecture': 'arch',
            'performance': 'perf'
        }
    },
    'development_process': {
        'enabled': True,
        'mappings': {
            'requirements': 'req',
            'dependencies': 'deps',
            'validation': 'val',
            'testing': 'test'
        }
    }
}

Quality Preservation

95% information retention target through comprehensive quality validation and evidence-based compression effectiveness monitoring:

Quality Preservation Standards

quality_preservation:
  minimum_thresholds:
    information_preservation: 0.95
    semantic_accuracy: 0.95
    technical_correctness: 0.98
    user_content_fidelity: 0.99
    
  validation_criteria:
    key_concept_retention: true
    technical_term_preservation: true
    code_example_accuracy: true
    reference_link_preservation: true

Quality Validation Framework

def _validate_compression_quality(self, compression_results, strategy) -> dict:
    """Validate compression quality against standards."""
    validation = {
        'overall_quality_met': True,
        'preservation_score': 0.0,
        'compression_efficiency': 0.0,
        'quality_issues': [],
        'quality_warnings': []
    }
    
    # Calculate preservation score
    total_preservation = sum(result.preservation_score for result in compression_results.values())
    validation['preservation_score'] = total_preservation / len(compression_results)
    
    # Quality threshold validation
    if validation['preservation_score'] < strategy.quality_threshold:
        validation['overall_quality_met'] = False
        validation['quality_issues'].append(
            f"Preservation score {validation['preservation_score']:.2f} below threshold {strategy.quality_threshold}"
        )

Quality Monitoring Metrics

• Information Preservation: Semantic content retention measurement
• Technical Correctness: Code accuracy and reference preservation
• Compression Efficiency: Token reduction vs. quality trade-off analysis
• User Content Fidelity: Project-specific content preservation verification

Quality Gate Integration

quality_validation = self._validate_compression_quality(
    compression_results, compression_strategy
)

if not quality_validation['overall_quality_met']:
    log_decision(
        "pre_compact",
        "quality_validation",
        "failed",
        f"Preservation score: {quality_validation['preservation_score']:.2f}"
    )

Configuration

Settings from compression.yaml providing comprehensive configuration management for adaptive compression strategies:

Core Configuration Structure

# Performance Targets
performance_targets:
  processing_time_ms: 150
  compression_ratio_target: 0.50
  quality_preservation_target: 0.95
  token_efficiency_gain: 0.40
  
# Adaptive Compression Strategy
adaptive_compression:
  context_awareness:
    user_expertise_factor: true
    project_complexity_factor: true
    domain_specific_optimization: true
    
  learning_integration:
    effectiveness_feedback: true
    user_preference_learning: true
    pattern_optimization: true

Compression Level Configuration

def __init__(self):
    # Load compression configuration
    try:
        self.compression_config = config_loader.load_config('compression')
    except FileNotFoundError:
        self.compression_config = self.hook_config.get('configuration', {})
    
    # Performance tracking
    self.performance_target_ms = config_loader.get_hook_config(
        'pre_compact', 'performance_target_ms', 150
    )

Dynamic Configuration Management

• Context-Aware Settings: Automatic adjustment based on content type and resource state
• Learning Integration: User preference adaptation and pattern optimization
• Performance Monitoring: Real-time configuration tuning based on effectiveness metrics
• Fallback Strategies: Graceful degradation when configuration loading fails

Integration with SuperClaude Framework

integration:
  mcp_servers:
    morphllm: "coordinate_compression_with_editing"
    serena: "memory_compression_strategies"
    
  modes:
    token_efficiency: "primary_compression_mode"
    task_management: "session_data_compression"
    
  learning_engine:
    effectiveness_tracking: true
    pattern_learning: true
    adaptation_feedback: true

MODE_Token_Efficiency Integration

Implementation of MODE_Token_Efficiency compression algorithms providing seamless integration with SuperClaude's token optimization behavioral mode:

Mode Integration Architecture

# MODE_Token_Efficiency.md → pre_compact.py implementation
class PreCompactHook:
    """
    Pre-compact hook implementing SuperClaude token efficiency intelligence.
    
    Implements MODE_Token_Efficiency.md algorithms:
    - 5-level compression strategy
    - Selective content classification
    - Symbol systems optimization
    - Quality preservation validation
    """

Behavioral Mode Coordination

• Auto-Activation: Resource usage >75%, large-scale operations, user brevity requests
• Compression Strategy Selection: Adaptive algorithm based on MODE configuration
• Quality Gate Integration: Validation against MODE preservation targets
• Performance Compliance: Sub-150ms execution aligned with MODE efficiency requirements

MODE Configuration Inheritance

# MODE_Token_Efficiency.md settings → compression.yaml
compression_levels:
  minimal: # MODE: 0-40% compression
    quality_threshold: 0.98
    symbol_systems: false
    
  efficient: # MODE: 40-70% compression  
    quality_threshold: 0.95
    symbol_systems: true
    
  compressed: # MODE: 70-85% compression
    quality_threshold: 0.90
    abbreviation_systems: true

Real-Time Mode Synchronization

def _determine_compression_strategy(self, context: dict, content_analysis: dict) -> CompressionStrategy:
    """Determine optimal compression strategy aligned with MODE_Token_Efficiency."""
    # MODE-compliant compression level determination
    compression_level = self.compression_engine.determine_compression_level({
        'resource_usage_percent': context.get('token_usage_percent', 0),
        'conversation_length': context.get('conversation_length', 0),
        'user_requests_brevity': context.get('user_requests_compression', False),
        'complexity_score': context.get('content_complexity', 0.0)
    })

Learning Integration with MODE

def _record_compression_learning(self, context, compression_results, quality_validation):
    """Record compression learning aligned with MODE adaptation."""
    self.learning_engine.record_learning_event(
        LearningType.PERFORMANCE_OPTIMIZATION,
        AdaptationScope.USER,
        context,
        {
            'compression_level': compression_level.value,
            'preservation_score': quality_validation['preservation_score'],
            'compression_efficiency': quality_validation['compression_efficiency']
        },
        overall_effectiveness,
        0.9  # High confidence in MODE-aligned compression metrics
    )

Framework Compliance Validation

• Symbol Systems: Direct implementation of MODE symbol mappings
• Abbreviation Systems: MODE-compliant technical abbreviation patterns
• Quality Preservation: MODE 95% information retention standards
• Selective Compression: MODE content classification and protection strategies

Key Features

Intelligent Compression Strategy Selection

def _determine_compression_strategy(self, context: dict, content_analysis: dict) -> CompressionStrategy:
    """
    Adaptive compression strategy based on:
    - Resource constraints and token usage
    - Content type classification
    - User preferences and expertise level
    - Quality preservation requirements
    """

Selective Content Preservation

• Framework Exclusion: Zero compression for SuperClaude components
• User Content Protection: High-fidelity preservation for project files
• Session Data Optimization: Efficient compression for operational data
• Quality-Gated Processing: Real-time validation against preservation targets

Symbol Systems Optimization

• Logic Flow Enhancement: Mathematical and directional symbols
• Status Communication: Visual progress and state indicators
• Domain-Specific Symbols: Technical context-aware representations
• Persona-Aware Selection: Symbol choice based on active domain expertise

Abbreviation Systems

• Technical Efficiency: Domain-specific shorthand for common terms
• Context-Sensitive Application: Intelligent abbreviation based on user familiarity
• Quality Preservation: Abbreviations that maintain semantic clarity
• Learning Integration: Pattern optimization based on effectiveness feedback

Quality-Gated Compression

• Real-Time Validation: Continuous quality monitoring during compression
• Preservation Score Tracking: Quantitative information retention measurement
• Adaptive Threshold Management: Dynamic quality targets based on content type
• Fallback Strategies: Graceful degradation when quality targets not met

Implementation Details

Compression Engine Architecture

from compression_engine import (
    CompressionEngine, CompressionLevel, ContentType, 
    CompressionResult, CompressionStrategy
)

class PreCompactHook:
    def __init__(self):
        self.compression_engine = CompressionEngine()
        self.performance_target_ms = 150

Content Analysis Pipeline

1. Content Characteristics Analysis: Complexity, repetition, technical density
2. Source Classification: Framework vs. user vs. session content identification
3. Compressibility Assessment: Potential optimization opportunity evaluation
4. Strategy Selection: Optimal compression level and technique determination
5. Quality Validation: Real-time preservation score monitoring

Performance Optimization Techniques

• Early Exit Strategy: Framework content bypass for immediate exclusion
• Parallel Processing: Concurrent analysis of content sections
• Intelligent Caching: Compression result reuse for similar patterns
• Selective Application: Compression only where beneficial and safe

Error Handling and Fallback

def _create_fallback_compression_config(self, compact_request: dict, error: str) -> dict:
    """Create fallback compression configuration on error."""
    return {
        'compression_enabled': False,
        'fallback_mode': True,
        'error': error,
        'quality': {
            'preservation_score': 1.0,  # No compression = perfect preservation
            'quality_met': False,       # But failed to optimize
            'issues': [f"Compression hook error: {error}"]
        }
    }

Results and Benefits

Typical Performance Metrics

• Token Reduction: 30-50% typical savings with quality preservation
• Processing Speed: 50-100ms typical execution time (well under 150ms target)
• Quality Preservation: ≥95% information retention consistently achieved
• Framework Protection: 100% exclusion success rate for SuperClaude components

Integration Benefits

• Seamless MODE Integration: Direct implementation of MODE_Token_Efficiency algorithms
• Real-Time Optimization: Sub-150ms compression decisions during active sessions
• Quality-First Approach: Preservation targets never compromised for efficiency gains
• Adaptive Intelligence: Learning-based optimization for improved effectiveness over time

User Experience Improvements

• Transparent Operation: Compression applied without user intervention or awareness
• Quality Assurance: Technical correctness and semantic accuracy maintained
• Performance Enhancement: Faster response times through optimized token usage
• Contextual Adaptation: Compression strategies tailored to specific use cases and domains

---

This hook serves as the core implementation of SuperClaude's intelligent token optimization system, providing evidence-based compression with adaptive strategies and quality-first preservation standards.