SuperClaude/Framework-Hooks/docs/QUICK_REFERENCE.md

Quick Reference

Essential commands and information for Framework-Hooks developers and users.

System Overview

• 7 hooks: Execute at specific Claude Code lifecycle events
• 9 shared modules: Common functionality across hooks
• 12+ config files: YAML-based configuration system
• 3-tier patterns: minimal/dynamic/learned pattern system
• Performance targets: <50ms to <200ms per hook

Installation Quick Check

# Verify Python version
python3 --version  # Need 3.8+

# Check directory structure
ls Framework-Hooks/
# Should see: hooks/ config/ patterns/ cache/ docs/

# Test hook execution
python3 Framework-Hooks/hooks/session_start.py

# Validate system
cd Framework-Hooks/hooks/shared
python3 validate_system.py --check-installation

Configuration Files

File	Purpose	Key Settings
logging.yaml	System logging	enabled: false (default)
performance.yaml	Timing targets	session_start: 50ms, pre_tool_use: 200ms
session.yaml	Session lifecycle	Context management, cleanup behavior
compression.yaml	Content compression	Selective compression rules
mcp_orchestration.yaml	MCP server routing	Server activation patterns

Performance Targets

Hook	Target Time	Timeout
session_start.py	<50ms	10s
pre_tool_use.py	<200ms	15s
post_tool_use.py	<100ms	10s
pre_compact.py	<150ms	15s
notification.py	<50ms	10s
stop.py	<100ms	15s
subagent_stop.py	<100ms	15s

Common Operations

Enable Logging

# Edit config/logging.yaml
logging:
  enabled: true
  level: "INFO"  # or DEBUG

Check System Health

cd Framework-Hooks/hooks/shared
python3 validate_system.py --health-check

Test Individual Hook

cd Framework-Hooks/hooks
python3 session_start.py       # Test session initialization
python3 pre_tool_use.py        # Test tool preparation

Clear Cache

# Reset learning data and cache
rm -rf Framework-Hooks/cache/*
# System will recreate on next run

View Recent Logs

# Check latest logs (if logging enabled)
tail -f Framework-Hooks/cache/logs/hooks-$(date +%Y-%m-%d).log

Hook Execution Flow

Session Start → Load Config → Detect Project → Apply Patterns →
Activate Features → [Work Session with Tool Use Hooks] → 
Record Learning → Save State → Session End

Directory Structure

Framework-Hooks/
├── hooks/                    # 7 hook scripts
│   ├── session_start.py      # <50ms - Session init
│   ├── pre_tool_use.py       # <200ms - Tool prep
│   ├── post_tool_use.py      # <100ms - Usage recording
│   ├── pre_compact.py        # <150ms - Context compression
│   ├── notification.py       # <50ms - Notifications
│   ├── stop.py               # <100ms - Session cleanup
│   ├── subagent_stop.py      # <100ms - Subagent coordination
│   └── shared/               # 9 shared modules
├── config/                   # 12+ YAML config files
├── patterns/                 # 3-tier pattern system
│   ├── minimal/              # Always loaded (3-5KB each)
│   ├── dynamic/              # On-demand (8-12KB each)
│   └── learned/              # User adaptations (10-20KB each)
├── cache/                    # Runtime cache and logs
└── docs/                     # Documentation

Shared Modules

Module	Purpose
framework_logic.py	SuperClaude framework integration
compression_engine.py	Context compression and optimization
learning_engine.py	Adaptive learning from usage
mcp_intelligence.py	MCP server coordination
pattern_detection.py	Project and usage pattern detection
intelligence_engine.py	Central intelligence coordination
logger.py	Structured logging system
yaml_loader.py	Configuration loading utilities
validate_system.py	System validation and health checks

Troubleshooting Quick Fixes

Hook Timeout

• Check performance targets in config/performance.yaml
• Clear cache: rm -rf cache/*
• Reduce pattern loading

Import Errors

# Verify shared modules path
ls Framework-Hooks/hooks/shared/
# Should show all 9 .py files

# Check permissions
chmod +x Framework-Hooks/hooks/*.py

YAML Errors

# Validate YAML files
python3 -c "
import yaml, glob
for f in glob.glob('config/*.yaml'):
    yaml.safe_load(open(f))
    print(f'{f}: OK')
"

No Log Output

# Enable in config/logging.yaml
logging:
  enabled: true
  level: "INFO"
  hook_logging:
    log_lifecycle: true

Configuration Shortcuts

Development Mode

# config/logging.yaml
logging:
  enabled: true
  level: "DEBUG"
development:
  debug_mode: true
  verbose_errors: true

Production Mode

# config/logging.yaml
logging:
  enabled: false
  level: "ERROR"

Reset to Defaults

# Backup first, then:
git checkout config/*.yaml
rm -rf cache/
rm -rf patterns/learned/

File Locations

• Hook scripts: hooks/*.py
• Configuration: config/*.yaml
• Logs: cache/logs/hooks-YYYY-MM-DD.log
• Learning data: cache/learning/
• Pattern cache: cache/patterns/
• Installation config: settings.json, superclaude-config.json

Debug Commands

# Full system validation
python3 hooks/shared/validate_system.py --full-check

# Check configuration integrity
python3 hooks/shared/validate_system.py --check-config

# Test pattern loading
python3 hooks/shared/pattern_detection.py --test-patterns

# Verify learning engine
python3 hooks/shared/learning_engine.py --test-learning

System Behavior

Default State

• All hooks enabled via settings.json
• Logging disabled for performance
• Conservative timeouts (10-15 seconds)
• Selective compression preserves user content
• Learning engine adapts to usage patterns

What Happens Automatically

1. Project detection - Identifies project type and loads patterns
2. Mode activation - Enables relevant SuperClaude modes
3. MCP coordination - Routes to appropriate servers
4. Performance optimization - Applies compression and caching
5. Learning adaptation - Records and learns from usage

Framework-Hooks operates transparently without requiring manual intervention.