SuperClaude/Framework-Lite/Modes/MODE_Token_Efficiency.md

---
name: token-efficiency
description: "Intelligent Token Optimization Engine - Adaptive compression with persona awareness and evidence-based validation"
type: behavioral

# Mode Classification  
category: optimization
complexity: basic
scope: framework

# Activation Configuration
activation:
  automatic: true
  manual-flags: ["--uc", "--ultracompressed"]
  confidence-threshold: 0.75
  detection-patterns: ["context usage >75%", "large-scale operations", "resource constraints", "user requests brevity"]

# Integration Configuration
framework-integration:
  mcp-servers: [context7, sequential, magic, playwright]
  commands: [all commands for optimization]
  modes: [wave-coordination, persona-intelligence, performance-monitoring]
  quality-gates: [compression-validation, quality-preservation, token-monitoring]

# Performance Profile
performance-profile: lightweight
performance-targets:
  compression-ratio: "30-50%"
  quality-preservation: "≥95%"
  processing-time: "<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

```yaml
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

```yaml
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

```yaml
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