SuperClaude/Framework-Hooks/docs/Configuration/superclaude-config.json.md

SuperClaude Master Configuration (superclaude-config.json)

Overview

The superclaude-config.json file serves as the master configuration file for the SuperClaude-Lite framework. This comprehensive JSON configuration controls all aspects of hook execution, MCP server integration, mode coordination, and quality gates within the framework.

Purpose and Role

The master configuration file acts as the central control system for:

• Hook Configuration Management: Defines behavior and settings for all 7 framework hooks
• MCP Server Integration: Coordinates intelligent routing and fallback strategies across servers
• Mode Orchestration: Manages behavioral mode activation and coordination patterns
• Quality Gate Enforcement: Implements the 8-step validation cycle throughout operations
• Performance Monitoring: Establishes targets and thresholds for optimization
• Learning System Integration: Enables cross-hook learning and adaptation

File Structure and Organization

1. Framework Metadata

{
  "superclaude": {
    "description": "SuperClaude-Lite Framework Configuration",
    "version": "1.0.0",
    "framework": "superclaude-lite",
    "enabled": true
  }
}

Purpose: Identifies framework version and overall enablement status.

2. Hook Configurations (hook_configurations)

The master configuration defines settings for all 7 SuperClaude hooks:

Session Start Hook

• Performance Target: 50ms initialization
• Features: Smart project context loading, automatic mode detection, MCP intelligence routing
• Configuration: Auto-detection, framework exclusion, intelligence activation
• Error Handling: Graceful fallback with context preservation

Pre-Tool Use Hook

• Performance Target: 200ms routing decision
• Features: Intelligent tool routing, MCP server selection, real-time adaptation
• Integration: All 6 MCP servers with quality gates and learning engine
• Configuration: Pattern detection, learning adaptations, fallback strategies

Post-Tool Use Hook

• Performance Target: 100ms validation
• Features: Quality validation, rules compliance, effectiveness measurement
• Validation Levels: Basic → Standard → Comprehensive → Production
• Configuration: Rules validation, principles alignment, learning integration

Pre-Compact Hook

• Performance Target: 150ms compression decision
• Features: Intelligent compression strategy selection, selective content preservation
• Compression Levels: Minimal (0-40%) → Emergency (95%+)
• Configuration: Framework protection, quality preservation target (95%)

Notification Hook

• Performance Target: 100ms processing
• Features: Just-in-time documentation loading, dynamic pattern updates
• Caching: Documentation (30min), patterns (60min), intelligence (15min)
• Configuration: Real-time learning, performance optimization through caching

Stop Hook

• Performance Target: 200ms analytics generation
• Features: Comprehensive session analytics, learning consolidation
• Analytics: Performance metrics, effectiveness measurement, optimization recommendations
• Configuration: Session persistence, performance tracking, recommendation generation

Subagent Stop Hook

• Performance Target: 150ms coordination analytics
• Features: Subagent performance analytics, delegation effectiveness measurement
• Task Management: Wave orchestration, parallel coordination, performance optimization
• Configuration: Delegation analytics, coordination measurement, learning integration

3. Global Configuration (global_configuration)

Framework Integration

• SuperClaude Compliance: Ensures adherence to framework standards
• YAML-Driven Logic: Hot-reload configuration capability
• Cross-Hook Coordination: Enables hooks to share context and learnings

Performance Monitoring

• Real-Time Tracking: Continuous performance measurement
• Target Enforcement: Automatic optimization when targets are missed
• Analytics: Performance trend analysis and optimization suggestions

Learning System

• Cross-Hook Learning: Shared knowledge across hook executions
• Adaptation Application: Real-time improvement based on effectiveness
• Pattern Recognition: Identifies successful operational patterns

Security

• Input Validation: Protects against malicious input
• Path Traversal Protection: Prevents unauthorized file access
• Resource Limits: Prevents resource exhaustion attacks

4. MCP Server Integration (mcp_server_integration)

Defines integration patterns for all 6 MCP servers:

Server Definitions

• Context7: Library documentation and framework patterns (standard profile)
• Sequential: Multi-step reasoning and complex analysis (intensive profile)
• Magic: UI component generation and design systems (standard profile)
• Playwright: Browser automation and testing (intensive profile)
• Morphllm: Intelligent editing with fast apply (lightweight profile)
• Serena: Semantic analysis and memory management (standard profile)

Coordination Settings

• Intelligent Routing: Automatic server selection based on task requirements
• Fallback Strategies: Graceful degradation when servers are unavailable
• Performance Optimization: Load balancing and resource management
• Learning Adaptation: Real-time improvement of routing decisions

5. Mode Integration (mode_integration)

Supported Modes

• Brainstorming: Interactive requirements discovery (sequential, context7)
• Task Management: Multi-layer task orchestration (serena, morphllm)
• Token Efficiency: Intelligent token optimization (morphllm)
• Introspection: Meta-cognitive analysis (sequential)

Mode-Hook Coordination

Each mode specifies which hooks it integrates with and which MCP servers it prefers.

6. Quality Gates (quality_gates)

Implements the 8-step validation cycle:

1. Syntax Validation: Language-specific syntax checking
2. Type Analysis: Type compatibility and inference
3. Code Quality: Linting rules and quality standards
4. Security Assessment: Vulnerability scanning and OWASP compliance
5. Testing Validation: Test coverage and quality assurance
6. Performance Analysis: Performance benchmarking and optimization
7. Documentation Verification: Documentation completeness and accuracy
8. Integration Testing: End-to-end validation and deployment readiness

Hook Integration

• Pre-Tool Use: Steps 1-2 (validation preparation)
• Post-Tool Use: Steps 3-5 (comprehensive validation)
• Stop: Steps 6-8 (final validation and analytics)

7. Cache Configuration (cache_configuration)

Cache Settings

• Cache Directory: ./cache for all cached data
• Retention Policies: Learning data (90 days), session data (30 days), performance data (365 days)
• Automatic Cleanup: Prevents cache bloat through scheduled cleanup

8. Logging Configuration (logging_configuration)

Logging Levels

• Log Level: INFO (configurable: ERROR, WARNING, INFO, DEBUG)
• Specialized Logging: Performance, error, learning, and hook execution logging
• Privacy: Sanitizes user content while preserving correlation data

9. Development Support (development_support)

Development Features

• Debugging: Optional debugging mode (disabled by default)
• Performance Profiling: Optional profiling capabilities
• Verbose Logging: Enhanced logging for development
• Test Mode: Specialized testing configuration

Key Configuration Sections

Performance Targets

Each hook has specific performance targets:

• Session Start: 50ms (critical priority)
• Pre-Tool Use: 200ms (high priority)
• Post-Tool Use: 100ms (medium priority)
• Pre-Compact: 150ms (high priority)
• Notification: 100ms (medium priority)
• Stop: 200ms (low priority)
• Subagent Stop: 150ms (medium priority)

Default Values and Meanings

Hook Enablement

All hooks are enabled by default ("enabled": true) to provide full framework functionality.

Performance Monitoring

Real-time tracking is enabled with target enforcement and optimization suggestions.

Learning System

Cross-hook learning is enabled to continuously improve framework effectiveness.

Security Settings

All security features are enabled by default for production-ready security.

Integration with Hooks

Configuration Loading

Hooks load configuration through the shared YAML loader system, enabling:

• Hot Reload: Configuration changes without restart
• Environment-Specific: Different configs for development/production
• Validation: Configuration validation before application

Cross-Hook Communication

The configuration enables hooks to:

• Share Context: Pass relevant information between hooks
• Coordinate Actions: Avoid conflicts through intelligent coordination
• Learn Together: Share effectiveness insights across hook executions

Performance Implications

Memory Usage

• Configuration Size: ~50KB typical configuration
• Cache Impact: Up to 100MB cache with automatic cleanup
• Learning Data: Persistent learning data with compression

Processing Overhead

• Configuration Loading: <10ms initial load
• Validation: <5ms per configuration access
• Hot Reload: <50ms configuration refresh

Network Impact

• MCP Coordination: Intelligent caching reduces network calls
• Documentation Loading: Just-in-time loading minimizes bandwidth usage

Configuration Best Practices

1. Performance Tuning

{
  "hook_configurations": {
    "session_start": {
      "performance_target_ms": 50,
      "configuration": {
        "auto_project_detection": true,
        "performance_monitoring": true
      }
    }
  }
}

Recommendation: Keep performance targets aggressive but achievable for your environment.

2. Security Hardening

{
  "global_configuration": {
    "security": {
      "input_validation": true,
      "path_traversal_protection": true,
      "timeout_protection": true,
      "resource_limits": true
    }
  }
}

Recommendation: Never disable security features in production environments.

3. Learning Optimization

{
  "global_configuration": {
    "learning_system": {
      "enabled": true,
      "cross_hook_learning": true,
      "effectiveness_tracking": true,
      "pattern_recognition": true
    }
  }
}

Recommendation: Enable learning system for continuous improvement, but monitor resource usage.

4. Mode Configuration

{
  "mode_integration": {
    "enabled": true,
    "modes": {
      "token_efficiency": {
        "hooks": ["pre_compact", "session_start"],
        "mcp_servers": ["morphllm"]
      }
    }
  }
}

Recommendation: Configure modes based on your primary use cases and available MCP servers.

5. Cache Management

{
  "cache_configuration": {
    "learning_data_retention_days": 90,
    "session_data_retention_days": 30,
    "automatic_cleanup": true
  }
}

Recommendation: Balance retention periods with storage requirements and privacy needs.

Troubleshooting

Common Configuration Issues

Performance Degradation

• Symptoms: Hooks exceeding performance targets
• Solutions: Adjust performance targets, enable caching, reduce feature complexity
• Monitoring: Check performance_monitoring settings

MCP Server Failures

• Symptoms: Routing failures, fallback activation
• Solutions: Verify MCP server availability, check fallback strategies
• Configuration: Review mcp_server_integration settings

Learning System Issues

• Symptoms: No adaptation observed, effectiveness not improving
• Solutions: Check learning data retention, verify effectiveness tracking
• Debug: Enable verbose learning logging

Memory Usage Issues

• Symptoms: High memory consumption, cache bloat
• Solutions: Reduce cache retention periods, enable automatic cleanup
• Monitoring: Review cache configuration and usage patterns

Configuration Validation

The framework validates configuration on startup:

• Schema Validation: Ensures proper JSON structure
• Value Validation: Checks ranges and dependencies
• Integration Validation: Verifies hook and MCP server consistency
• Security Validation: Ensures security settings are appropriate

Related Documentation

• Hook Implementation: See individual hook documentation in /docs/Hooks/
• MCP Integration: Reference MCP server documentation for specific server configurations
• Mode Documentation: Review mode-specific documentation for behavioral patterns
• Performance Monitoring: See performance configuration documentation for optimization strategies

Version History

• v1.0.0: Initial SuperClaude-Lite configuration with all 7 hooks and 6 MCP servers
• Full hook lifecycle support with learning and performance monitoring
• Comprehensive quality gates implementation
• Mode integration with behavioral pattern support