SuperClaude/Framework-Hooks/docs/Integration.md

Framework-Hooks Integration with SuperClaude

Overview

The Framework-Hooks system implements SuperClaude framework patterns through Claude Code lifecycle hooks. The system executes 7 Python hooks during session lifecycle events to provide mode detection, MCP server routing, and configuration management.

1. Hook Implementation Architecture

Lifecycle Hook Integration

The Framework-Hooks system implements SuperClaude patterns through 7 Python hooks:

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Runtime                      │
├─────────────────────────────────────────────────────────────┤
│  SessionStart → PreTool → PostTool → PreCompact → Notify   │
│       ↓            ↓         ↓           ↓          ↓       │
│   Mode/MCP     Server      Learning    Token        Pattern │
│   Detection    Selection   Tracking    Compression  Updates │
└─────────────────────────────────────────────────────────────┘

SuperClaude Framework Implementation

Each hook implements specific SuperClaude framework aspects:

• session_start.py: MODE detection patterns from MODE_*.md files
• pre_tool_use.py: MCP server routing from ORCHESTRATOR.md patterns
• post_tool_use.py: Learning and effectiveness tracking
• pre_compact.py: Token efficiency patterns from MODE_Token_Efficiency.md
• stop.py/subagent_stop.py: Session analytics and coordination tracking

Configuration Integration

Hook behavior is configured through:

• settings.json: Hook timeouts and execution commands
• performance.yaml: Performance targets (50ms session_start, 200ms pre_tool_use, etc.)
• modes.yaml: Mode detection patterns and triggers
• pattern files: Project-specific behavior in minimal/, dynamic/, learned/ directories

2. Hook Lifecycle Integration

Hook Execution Flow

The hooks execute during specific Claude Code lifecycle events:

Hook Execution Sequence:
  1. SessionStart (10s timeout)
     - Detects project type (Python, React, etc.)
     - Loads appropriate pattern files
     - Activates SuperClaude modes based on user input
     - Routes to MCP servers

  2. PreToolUse (15s timeout)
     - Analyzes operation type and complexity
     - Selects optimal MCP servers
     - Applies performance optimizations

  3. PostToolUse (10s timeout)
     - Validates operation results
     - Records learning data and effectiveness metrics
     - Updates user preferences

  4. PreCompact (15s timeout)
     - Applies token compression strategies
     - Preserves framework content (0% compression)
     - Uses symbols and abbreviations for efficiency

  5. Notification (10s timeout)
     - Updates pattern caches
     - Refreshes configurations
     - Handles runtime notifications

  6. Stop (15s timeout)
     - Generates session analytics
     - Saves learning data to files
     - Creates performance metrics

  7. SubagentStop (15s timeout)
     - Tracks delegation performance
     - Records coordination effectiveness

Integration Points

• Pattern Loading: Minimal patterns loaded during session_start for project-specific behavior
• Learning Persistence: User preferences and effectiveness data saved to learned/ directory
• Performance Monitoring: Hook execution times tracked against targets in performance.yaml
• Configuration Updates: YAML configuration changes applied during runtime

3. MCP Server Coordination

Server Routing Logic

The pre_tool_use hook routes operations to MCP servers based on detected patterns:

MCP Server Selection:
  Magic: 
    - Triggers: UI keywords (component, button, form, modal)
    - Use case: UI component generation and design

  Sequential:
    - Triggers: Analysis keywords (analyze, debug, complex)
    - Use case: Multi-step reasoning and systematic analysis

  Context7:
    - Triggers: Documentation keywords (library, framework, api)
    - Use case: Library documentation and best practices

  Playwright:
    - Triggers: Testing keywords (test, e2e, browser)
    - Use case: Browser automation and testing

  Morphllm vs Serena:
    - Morphllm: Simple edits (<10 files, token optimization)
    - Serena: Complex operations (>5 files, semantic analysis)

  Auto-activation:
    - Project patterns trigger appropriate server combinations
    - User preferences influence server selection
    - Fallback strategies for unavailable servers

Server Configuration

Server routing is configured through:

• mcp_intelligence.py (31KB) - Core routing logic and server capability matching
• mcp_activation.yaml - Dynamic patterns for server activation
• Project patterns - Server preferences by project type (e.g., python_project.yaml specifies Serena + Context7)
• Learning data - User preferences for server selection stored in learned/ directory

4. SuperClaude Mode Integration

Mode Detection

The session_start hook detects user intent and activates SuperClaude modes:

Mode Detection Patterns:
  Brainstorming Mode:
    - Triggers: "not sure", "thinking about", "explore", ambiguous requests
    - Implementation: Activates interactive requirements discovery

  Task Management Mode:
    - Triggers: Multi-file operations, "build", "implement", complexity >0.4
    - Implementation: Enables delegation and wave orchestration

  Token Efficiency Mode:
    - Triggers: Resource constraints >75%, "--uc", "brief"
    - Implementation: Activates compression in pre_compact hook

  Introspection Mode:
    - Triggers: "analyze reasoning", meta-cognitive requests
    - Implementation: Enables framework compliance analysis

Mode Implementation

Modes are implemented across multiple hooks:

• session_start.py: Detects mode triggers and sets activation flags
• pre_compact.py: Implements token efficiency compression strategies
• post_tool_use.py: Validates mode-specific behaviors and tracks effectiveness
• stop.py: Records mode usage analytics and learning data

5. Configuration and Validation

Configuration Management

The system uses 19 YAML configuration files to define behavior:

• performance.yaml (345 lines): Performance targets and monitoring thresholds
• modes.yaml: Mode detection patterns and activation triggers
• validation.yaml: Quality gate definitions and validation rules
• compression.yaml: Token efficiency settings and compression levels
• session.yaml: Session lifecycle and analytics configuration

Validation Implementation

Validation is distributed across hooks:

• pre_tool_use.py: Basic validation before tool execution
• post_tool_use.py: Results validation and quality assessment
• validate_system.py (32KB): System health checks and validation utilities
• stop.py: Final session validation and analytics generation

Learning and Analytics

The system tracks effectiveness and adapts behavior:

• learning_engine.py (40KB): Records user preferences and operation effectiveness
• Learned patterns: Stored in patterns/learned/ directory
• Performance tracking: Hook execution times and success rates
• User preferences: Saved across sessions for personalized behavior

6. Session Management

Session Integration

Framework-Hooks integrates with Claude Code session lifecycle:

• Session Start: session_start hook runs when Claude Code sessions begin
• Tool Execution: pre/post_tool_use hooks run for each tool operation
• Token Optimization: pre_compact hook runs during token compression
• Session End: stop hook runs when sessions complete

Data Persistence

Session data is persisted through:

• Learning Records: User preferences saved to patterns/learned/ directory
• Performance Metrics: Hook execution times and success rates logged
• Session Analytics: Summary data generated by stop hook
• Pattern Updates: Dynamic patterns updated based on usage

Performance Monitoring

The system tracks performance against configuration targets:

• Hook Timing: Each hook execution timed and compared to performance.yaml targets
• Resource Usage: Memory and CPU monitoring during hook execution
• Success Rates: Operation effectiveness tracked by learning_engine.py
• User Satisfaction: Implicit feedback through continued usage patterns

7. Pattern System

Pattern Directory Structure

The system uses a three-tier pattern organization:

patterns/
  minimal/        # Essential patterns loaded during session start
    - python_project.yaml: Python project detection and configuration
    - react_project.yaml: React project patterns and MCP routing
    
  dynamic/        # Runtime patterns for adaptive behavior  
    - mode_detection.yaml: SuperClaude mode triggers and activation
    - mcp_activation.yaml: MCP server routing patterns
    
  learned/        # User preference and effectiveness data
    - user_preferences.yaml: Personal configuration adaptations
    - project_optimizations.yaml: Project-specific learned patterns

Pattern Processing

Pattern loading and application:

• pattern_detection.py (45KB): Core pattern recognition and matching logic
• Session startup: Minimal patterns loaded based on detected project type
• Runtime updates: Dynamic patterns applied during hook execution
• Learning updates: Successful patterns saved to learned/ directory for future use

Pattern Configuration

Patterns define:

• Project detection: File patterns and dependency analysis for project type identification
• MCP server routing: Which servers to activate for different operation types
• Mode triggers: Keywords and contexts that activate SuperClaude modes
• Performance targets: Project-specific timing and resource goals

8. Implementation Summary

System Implementation

The Framework-Hooks system implements SuperClaude framework patterns through:

Core Components:

• 7 Python lifecycle hooks (17 Python files total)
• 19 YAML configuration files
• 3-tier pattern system (minimal/dynamic/learned)
• 9 shared modules providing common functionality

Key Features:

• Project type detection and pattern-based configuration
• SuperClaude mode activation based on user input patterns
• MCP server routing with fallback strategies
• Token compression with selective framework protection
• Learning system that adapts to user preferences
• Performance monitoring against configured targets

Integration Points:

• Claude Code lifecycle hooks via settings.json
• SuperClaude framework mode implementations
• MCP server coordination and routing
• Pattern-based project and operation detection
• Cross-session learning and preference persistence

The system provides a Python-based implementation of SuperClaude framework concepts, enabling intelligent behavior through configuration-driven lifecycle hooks that execute during Claude Code sessions.