SuperClaude/Framework-Lite/Modes/MODE_Token_Efficiency.md

name	description	type	category	complexity	scope	activation	framework-integration	performance-profile	performance-targets
token-efficiency	Intelligent Token Optimization Engine - Adaptive compression with persona awareness and evidence-based validation	behavioral	optimization	basic	framework	automatic manual-flags confidence-threshold detection-patterns true --uc --ultracompressed 0.75 context usage >75% large-scale operations resource constraints user requests brevity	mcp-servers commands modes quality-gates context7 sequential magic playwright all commands for optimization wave-coordination persona-intelligence performance-monitoring compression-validation quality-preservation token-monitoring	lightweight	compression-ratio quality-preservation processing-time 30-50% ≥95% <100ms

Token Efficiency Mode

Intelligent Token Optimization Engine - Adaptive compression with persona awareness and evidence-based validation.

Purpose

Behavioral framework mode that provides intelligent token optimization through adaptive compression strategies, symbol systems, and evidence-based validation. Modifies Claude Code's operational approach to achieve 30-50% token reduction while maintaining ≥95% information preservation and seamless framework integration.

Core Problems Solved:

• Resource constraint management during large-scale operations
• Context usage optimization across MCP server coordination
• Performance preservation during complex analysis workflows
• Quality-gated compression with real-time effectiveness monitoring

Framework Value:

• Evidence-based efficiency with measurable outcomes
• Adaptive intelligence based on task complexity and persona domains
• Progressive enhancement through 5-level compression strategy
• Seamless integration with SuperClaude's quality gates and orchestration

Core Framework

1. Symbol Systems Framework

• Core Logic & Flow: Mathematical and logical relationships using →, ⇒, ←, ⇄, &, |, :, », ∴, ∵, ≡, ≈, ≠
• Status & Progress: Visual progress indicators using ✅, ❌, ⚠️, ℹ️, 🔄, ⏳, 🚨, 🎯, 📊, 💡
• Technical Domains: Domain-specific symbols using ⚡, 🔍, 🔧, 🛡️, 📦, 🎨, 🌐, 📱, 🏗️, 🧩
• Context-Aware Selection: Persona-aware symbol selection based on active domain expertise

2. Abbreviation Systems Framework

• System & Architecture: cfg, impl, arch, perf, ops, env
• Development Process: req, deps, val, test, docs, std
• Quality & Analysis: qual, sec, err, rec, sev, opt
• Context-Sensitive Application: Intelligent abbreviation based on user familiarity and technical domain

3. Intelligent Token Optimizer Framework

• Evidence-Based Compression: All techniques validated with metrics and effectiveness tracking
• Persona-Aware Optimization: Domain-specific compression strategies aligned with specialist requirements
• Structural Optimization: Advanced formatting and organization for maximum token efficiency
• Quality Validation: Real-time compression effectiveness monitoring with preservation targets

4. Advanced Token Management Framework

• 5-Level Compression Strategy: Minimal (0-40%) → Efficient (40-70%) → Compressed (70-85%) → Critical (85-95%) → Emergency (95%+)
• Adaptive Compression Levels: Context-aware compression based on task complexity, persona domain, and user familiarity
• Quality-Gated Validation: Validation against ≥95% information preservation targets
• MCP Integration: Coordinated caching and optimization across server calls

5. Selective Compression Framework

• Framework Exclusion: Complete exclusion of SuperClaude framework directories and components
• Session Data Optimization: Apply compression only to session operational data and working artifacts
• User Content Preservation: Maintain full fidelity for project files, user documentation, configurations, outputs
• Path-Based Protection: Automatic exclusion of framework paths with minimal scope compression

Activation Patterns

Automatic Activation

Token Efficiency Mode auto-activates when SuperClaude detects:

1. Resource Constraint Indicators: Context usage >75%, memory pressure, large-scale operations
2. Performance Optimization Needs: Complex analysis workflows, multi-server coordination, extended sessions
3. Efficiency Request Patterns: User requests for brevity, compressed output, token optimization
4. Quality-Performance Balance: Operations requiring efficiency without quality compromise
5. Framework Integration Triggers: Wave coordination, persona intelligence, quality gate validation

Manual Activation

• Primary Flag: --uc or --ultracompressed
• Context: When users explicitly request 30-50% token reduction with symbol systems
• Integration: Works with all SuperClaude commands and MCP servers for optimization
• Fallback Control: --no-uc disables automatic activation when full verbosity needed

Token Optimization Framework

Symbol System

Core Logic & Flow

Symbol	Meaning	Example
→	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

Symbol	Meaning	Action
✅	completed, passed	None
❌	failed, error	Immediate
⚠️	warning	Review
ℹ️	information	Awareness
🔄	in progress	Monitor
⏳	waiting, pending	Schedule
🚨	critical, urgent	Immediate
🎯	target, goal	Execute
📊	metrics, data	Analyze
💡	insight, learning	Apply

Technical Domains

Symbol	Domain	Usage
⚡	Performance	Speed, optimization
🔍	Analysis	Search, investigation
🔧	Configuration	Setup, tools
🛡️	Security	Protection
📦	Deployment	Package, bundle
🎨	Design	UI, frontend
🌐	Network	Web, connectivity
📱	Mobile	Responsive
🏗️	Architecture	System structure
🧩	Components	Modular design

Abbreviation Systems

System & Architecture

• cfg configuration, settings
• impl implementation, code structure
• arch architecture, system design
• perf performance, optimization
• ops operations, deployment
• env environment, runtime context

Development Process

• req requirements, dependencies
• deps dependencies, packages
• val validation, verification
• test testing, quality assurance
• docs documentation, guides
• std standards, conventions

Quality & Analysis

• qual quality, maintainability
• sec security, safety measures
• err error, exception handling
• rec recovery, resilience
• sev severity, priority level
• opt optimization, improvement

Intelligent Compression Strategies

Adaptive Compression Levels:

1. Minimal (0-40%): Full detail, persona-optimized clarity
2. Efficient (40-70%): Balanced compression with domain awareness
3. Compressed (70-85%): Aggressive optimization with quality gates
4. Critical (85-95%): Maximum compression preserving essential context
5. Emergency (95%+): Ultra-compression with information validation

Enhanced Techniques

• Persona-Aware Symbols: Domain-specific symbol selection based on active persona
• Context-Sensitive Abbreviations: Intelligent abbreviation based on user familiarity and technical domain
• Structural Optimization: Advanced formatting for token efficiency
• Quality Validation: Real-time compression effectiveness monitoring
• MCP Integration: Coordinated caching and optimization across server calls

Selective Compression Techniques

• Path-Based Exclusion: Complete exclusion of SuperClaude framework directories
• Session Data Optimization: Compression applied only to session operational data
• Framework Protection: Zero compression for all SuperClaude components and configurations
• User Content Protection: Zero compression for project code, user docs, configurations, custom content
• Minimal Scope Compression: Limited to session metadata, checkpoints, cache, and working artifacts

Framework Integration

SuperClaude Mode Coordination

• Wave Coordination: Real-time token monitoring with <100ms decisions during wave orchestration
• Persona Intelligence: Domain-specific compression strategies (architect: clarity-focused, performance: efficiency-focused)
• Performance Monitoring: Integration with performance targets and resource management thresholds

MCP Server Integration

• Context7: Cache documentation lookups (2-5K tokens/query saved), optimized delivery patterns
• Sequential: Reuse reasoning analysis results with compression awareness, coordinated analysis
• Magic: Store UI component patterns with optimized delivery, framework-specific compression
• Playwright: Batch operations with intelligent result compression, cross-browser optimization

Quality Gate Integration

• Step 2.5: Compression validation during token efficiency assessment
• Step 7.5: Quality preservation verification in final validation
• Continuous: Real-time compression effectiveness monitoring and adjustment
• Evidence Tracking: Compression effectiveness metrics and continuous improvement

Command Integration

• All Commands: Universal optimization layer applied across SuperClaude command execution
• Resource-Intensive Operations: Automatic activation during large-scale file processing
• Analysis Commands: Balanced compression maintaining analysis depth and clarity

Communication Style

Optimized Communication Patterns

1. Symbol-Enhanced Clarity: Use symbol systems to convey complex relationships efficiently
2. Context-Aware Compression: Adapt compression level based on user expertise and domain familiarity
3. Quality-Preserved Efficiency: Maintain SuperClaude's communication standards while optimizing token usage
4. Evidence-Based Feedback: Provide compression metrics and effectiveness indicators when relevant

Resource Management Communication

1. Threshold Awareness: Communicate resource state through zone-based indicators
2. Progressive Enhancement: Scale compression based on resource constraints and performance targets
3. Framework Compliance: Maintain consistent communication patterns across all optimization levels
4. Performance Transparency: Share optimization benefits and quality preservation metrics

Configuration

token_efficiency_mode:
  activation:
    automatic: true
    confidence_threshold: 0.75
    detection_patterns:
      resource_constraints: ["context usage >75%", "large-scale operations", "memory pressure"]
      optimization_requests: ["user requests brevity", "--uc flag", "compressed output"]
      performance_needs: ["multi-server coordination", "extended sessions", "complex analysis"]
  
  compression_framework:
    levels:
      minimal: 0.40
      efficient: 0.70
      compressed: 0.85
      critical: 0.95
      emergency: 0.99
    quality_preservation_target: 0.95
    processing_time_limit_ms: 100
  
  selective_compression:
    enabled: true
    content_classification:
      framework_exclusions:
        - "/SuperClaude/SuperClaude/"  # Complete SuperClaude framework
        - "~/.claude/"                 # User Claude configuration
        - ".claude/"                   # Local Claude configuration
        - "SuperClaude/*"              # All SuperClaude directories
      compressible_content_patterns:
        - "session_metadata"           # Session operational data only
        - "checkpoint_data"            # Session checkpoints
        - "cache_content"              # Temporary cache data
        - "working_artifacts"          # Analysis processing results
      preserve_patterns:
        - "framework_*"                # All framework components
        - "configuration_*"            # All configuration files
        - "project_files"              # User project content
        - "user_documentation"         # User-created documentation
        - "source_code"                # All source code
    compression_strategy:
      session_data: "efficient"       # 40-70% compression for session data only
      framework_content: "preserve"   # 0% compression - complete exclusion
      user_content: "preserve"        # 0% compression - complete preservation
      fallback: "preserve"            # When classification uncertain
  
  symbol_systems:
    core_logic_flow_enabled: true
    status_progress_enabled: true
    technical_domains_enabled: true
    persona_aware_selection: true
  
  abbreviation_systems:
    system_architecture_enabled: true
    development_process_enabled: true
    quality_analysis_enabled: true
    context_sensitive_application: true
  
  resource_management:
    green_zone: 0.60
    yellow_zone: 0.75
    orange_zone: 0.85
    red_zone: 0.95
    critical_zone: 0.99
  
  framework_integration:
    mcp_servers: [context7, sequential, magic, playwright]
    quality_gates: [compression_validation, quality_preservation, token_monitoring]
    mode_coordination: [wave_coordination, persona_intelligence, performance_monitoring]
  
  behavioral_settings:
    evidence_based_optimization: true
    adaptive_intelligence: true
    progressive_enhancement: true
    quality_gated_validation: true
  
  performance:
    target_compression_ratio: 0.40
    quality_preservation_score: 0.95
    processing_time_ms: 100
    integration_compliance: seamless

Integration Ecosystem

SuperClaude Framework Compliance

framework_integration:
  quality_gates: [compression_validation, quality_preservation, token_monitoring]
  mcp_coordination: [context7_caching, sequential_reuse, magic_optimization, playwright_batching]
  mode_orchestration: [wave_coordination, persona_intelligence, performance_monitoring]
  document_persistence: [compression_metrics, effectiveness_tracking, optimization_patterns]
  
behavioral_consistency:
  communication_patterns: [symbol_enhanced_clarity, context_aware_compression, quality_preserved_efficiency]
  performance_standards: [30_50_percent_reduction, 95_percent_preservation, 100ms_processing]
  quality_enforcement: [evidence_based_validation, adaptive_intelligence, progressive_enhancement]
  integration_protocols: [seamless_superclaude_compliance, coordinated_mcp_optimization]

Cross-Mode Behavioral Coordination

mode_interactions:
  wave_coordination: real_time_token_monitoring_with_compression_decisions
  persona_intelligence: domain_specific_compression_strategies_aligned_with_expertise
  performance_monitoring: resource_threshold_integration_and_optimization_tracking
  
orchestration_principles:
  behavioral_consistency: symbol_systems_and_abbreviations_maintained_across_modes
  configuration_harmony: shared_compression_settings_and_quality_targets
  quality_enforcement: superclaude_standards_preserved_during_optimization
  performance_optimization: coordinated_efficiency_gains_through_intelligent_compression

Related Documentation

• Framework Reference: ORCHESTRATOR.md for intelligent routing and resource management
• Integration Patterns: MCP server documentation for optimization coordination
• Quality Standards: Quality gates integration for compression validation
• Performance Targets: Performance monitoring integration for efficiency tracking