External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-29 16:16:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Complete Framework-Hooks documentation overhaul

Browse Source 
Major documentation update focused on technical accuracy and developer clarity:

Documentation Changes:
- Rewrote README.md with focus on hooks system architecture
- Updated all core docs (Overview, Integration, Performance) to match implementation
- Created 6 missing configuration docs for undocumented YAML files
- Updated all 7 hook docs to reflect actual Python implementations
- Created docs for 2 missing shared modules (intelligence_engine, validate_system)
- Updated all 5 pattern docs with real YAML examples
- Added 4 essential operational docs (INSTALLATION, TROUBLESHOOTING, CONFIGURATION, QUICK_REFERENCE)

Key Improvements:
- Removed all marketing language in favor of humble technical documentation
- Fixed critical configuration discrepancies (logging defaults, performance targets)
- Used actual code examples and configuration from implementation
- Complete coverage: 15 configs, 10 modules, 7 hooks, 3 pattern tiers
- Based all documentation on actual file review and code analysis

Technical Accuracy:
- Corrected performance targets to match performance.yaml
- Fixed timeout values from settings.json (10-15 seconds)
- Updated module count and descriptions to match actual shared/ directory
- Aligned all examples with actual YAML and Python implementations

The documentation now provides accurate, practical information for developers
working with the Framework-Hooks system, focusing on what it actually does
rather than aspirational features.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
2025-08-06 15:13:07 +02:00
parent ff7eda0e8a
commit 9edf3f8802
52 changed files with 4990 additions and 10202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

342
Framework-Hooks/docs/Configuration/settings.json.md
View File

@@ -2,22 +2,19 @@
## Overview
The `settings.json` file defines the Claude Code hook configuration settings for the SuperClaude-Lite framework. This file specifies the execution patterns, timeouts, and command paths for all framework hooks, serving as the bridge between Claude Code's hook system and the SuperClaude implementation.
The `settings.json` file defines the Claude Code hook configuration settings for the SuperClaude-Lite framework. This file registers all framework hooks with Claude Code and specifies their execution parameters.
## Purpose and Role
The hook settings configuration serves as:
This configuration provides:
- **Hook Registration**: Registers all 7 SuperClaude hooks with Claude Code
- **Execution Configuration**: Defines command paths, timeouts, and execution patterns
- **Execution Configuration**: Defines command paths, timeouts, and execution patterns
- **Universal Matching**: Applies hooks to all operations through `"matcher": "*"`
- **Timeout Management**: Establishes execution time limits for each hook type
- **Command Coordination**: Links hook names to Python implementation files
- **Timeout Management**: Establishes execution time limits for each hook
## File Structure and Organization
## Configuration Structure
### 1. Hook Registration Pattern
The configuration follows Claude Code's hook registration format:
### Basic Pattern
```json
{
"hooks": {
@@ -27,8 +24,8 @@ The configuration follows Claude Code's hook registration format:
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/hook_file.py",
"timeout": 10
"command": "python3 ~/.claude/hooks/script.py",
"timeout": 15
}
]
}
@@ -37,7 +34,9 @@ The configuration follows Claude Code's hook registration format:
}
```
### 2. Hook Definitions
### Hook Definitions
The actual configuration registers these hooks:
#### SessionStart Hook
```json
@@ -46,7 +45,7 @@ The configuration follows Claude Code's hook registration format:
"matcher": "*",
"hooks": [
{
"type": "command",
"type": "command",
"command": "python3 ~/.claude/hooks/session_start.py",
"timeout": 10
}
@@ -55,10 +54,9 @@ The configuration follows Claude Code's hook registration format:
]
```
**Purpose**: Initializes SuperClaude framework at the beginning of each Claude Code session
**Timeout**: 10 seconds (generous for initialization tasks)
**Execution**: Runs for every session start (`"matcher": "*"`)
**Implementation**: `/session_start.py` handles project detection, mode activation, and context loading
**Purpose**: Initialize sessions and detect project context
**Timeout**: 10 seconds for session initialization
**Execution**: Runs at the start of every Claude Code session
#### PreToolUse Hook
```json
@@ -68,7 +66,7 @@ The configuration follows Claude Code's hook registration format:
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/pre_tool_use.py",
"command": "python3 ~/.claude/hooks/pre_tool_use.py",
"timeout": 15
}
]
@@ -76,16 +74,15 @@ The configuration follows Claude Code's hook registration format:
]
```
**Purpose**: Intelligent tool routing and MCP server selection before tool execution
**Timeout**: 15 seconds (allows for MCP coordination and decision-making)
**Purpose**: Pre-process tool usage and provide intelligent routing
**Timeout**: 15 seconds for analysis and routing decisions
**Execution**: Runs before every tool use operation
**Implementation**: `/pre_tool_use.py` handles orchestrator logic, MCP routing, and performance optimization
#### PostToolUse Hook
```json
"PostToolUse": [
{
"matcher": "*",
"matcher": "*",
"hooks": [
{
"type": "command",
@@ -97,10 +94,9 @@ The configuration follows Claude Code's hook registration format:
]
```
**Purpose**: Quality validation, rules compliance, and effectiveness measurement after tool execution
**Timeout**: 10 seconds (sufficient for validation cycles)
**Purpose**: Post-process tool results and apply quality gates
**Timeout**: 10 seconds for result analysis and validation
**Execution**: Runs after every tool use operation
**Implementation**: `/post_tool_use.py` handles quality gates, rule validation, and learning integration
#### PreCompact Hook
```json
@@ -109,7 +105,7 @@ The configuration follows Claude Code's hook registration format:
"matcher": "*",
"hooks": [
{
"type": "command",
"type": "command",
"command": "python3 ~/.claude/hooks/pre_compact.py",
"timeout": 15
}
@@ -118,10 +114,9 @@ The configuration follows Claude Code's hook registration format:
]
```
**Purpose**: Token efficiency optimization and intelligent compression before context compaction
**Timeout**: 15 seconds (allows for compression analysis and strategy selection)
**Execution**: Runs before context compaction operations
**Implementation**: `/pre_compact.py` handles compression strategies, selective optimization, and quality preservation
**Purpose**: Apply intelligent compression before context compaction
**Timeout**: 15 seconds for compression analysis and application
**Execution**: Runs before Claude Code compacts conversation context
#### Notification Hook
```json
@@ -131,7 +126,7 @@ The configuration follows Claude Code's hook registration format:
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/notification.py",
"command": "python3 ~/.claude/hooks/notification.py",
"timeout": 10
}
]
@@ -139,10 +134,9 @@ The configuration follows Claude Code's hook registration format:
]
```
**Purpose**: Just-in-time documentation loading and dynamic pattern updates
**Timeout**: 10 seconds (sufficient for notification processing)
**Execution**: Runs for all notification events
**Implementation**: `/notification.py` handles documentation caching, pattern updates, and intelligence refresh
**Purpose**: Handle notifications and update learning patterns
**Timeout**: 10 seconds for notification processing
**Execution**: Runs when Claude Code sends notifications
#### Stop Hook
```json
@@ -160,10 +154,9 @@ The configuration follows Claude Code's hook registration format:
]
```
**Purpose**: Session analytics, learning consolidation, and cleanup at session end
**Timeout**: 15 seconds (allows for comprehensive analytics generation)
**Execution**: Runs at session termination
**Implementation**: `/stop.py` handles session persistence, analytics generation, and cleanup operations
**Purpose**: Session cleanup and analytics generation
**Timeout**: 15 seconds for cleanup and analysis
**Execution**: Runs when Claude Code session ends
#### SubagentStop Hook
```json
@@ -172,7 +165,7 @@ The configuration follows Claude Code's hook registration format:
"matcher": "*",
"hooks": [
{
"type": "command",
"type": "command",
"command": "python3 ~/.claude/hooks/subagent_stop.py",
"timeout": 15
}
@@ -181,236 +174,71 @@ The configuration follows Claude Code's hook registration format:
]
```
**Purpose**: Task management analytics and subagent coordination cleanup
**Timeout**: 15 seconds (allows for delegation analytics and coordination cleanup)
**Execution**: Runs when subagents terminate
**Implementation**: `/subagent_stop.py` handles task management analytics, delegation effectiveness, and coordination cleanup
**Purpose**: Subagent coordination and task management analytics
**Timeout**: 15 seconds for subagent cleanup
**Execution**: Runs when Claude Code subagent sessions end
## Key Configuration Sections
## Key Configuration Elements
### 1. Universal Matching Pattern
### Universal Matcher
- **Pattern**: `"matcher": "*"`
- **Effect**: All hooks apply to every operation
- **Purpose**: Ensures consistent framework behavior across all interactions
All hooks use `"matcher": "*"` which means:
- **Applies to All Operations**: Every hook runs for all matching events
- **No Filtering**: No operation-specific filtering at the settings level
- **Complete Coverage**: Ensures comprehensive framework integration
- **Consistent Behavior**: All operations receive full SuperClaude treatment
### Command Type
- **Type**: `"command"`
- **Execution**: Runs external Python scripts
- **Environment**: Uses system Python 3 installation
### 2. Command Type Specification
### File Paths
- **Location**: `~/.claude/hooks/`
- **Naming**: Matches hook names in snake_case (e.g., `session_start.py`)
- **Permissions**: Scripts must be executable
All hooks use `"type": "command"` which indicates:
- **External Process Execution**: Each hook runs as a separate Python process
- **Isolation**: Hook failures don't crash the main Claude Code process
- **Resource Management**: Each hook has independent resource allocation
- **Error Handling**: Individual hook errors can be captured and handled
### Timeout Values
- **SessionStart**: 10 seconds (session initialization)
- **PreToolUse**: 15 seconds (analysis and routing)
- **PostToolUse**: 10 seconds (result processing)
- **PreCompact**: 15 seconds (compression)
- **Notification**: 10 seconds (notification handling)
- **Stop**: 15 seconds (cleanup and analytics)
- **SubagentStop**: 15 seconds (subagent coordination)
### 3. Python Path Configuration
## Installation Requirements
All commands use `python3 ~/.claude/hooks/` path structure:
- **Standard Location**: Hooks installed in user's Claude configuration directory
- **Python 3 Requirement**: Ensures modern Python runtime
- **User-Specific**: Hooks are user-specific, not system-wide
- **Consistent Structure**: All hooks follow the same file organization pattern
### File Installation
The framework installation process must:
1. Copy Python hook scripts to `~/.claude/hooks/`
2. Set executable permissions on all hook scripts
3. Install this `settings.json` file for Claude Code to read
4. Verify Python 3 is available in the system PATH
### 4. Timeout Configuration
Timeout values are strategically set based on hook complexity:
#### Short Timeouts (10 seconds)
- **SessionStart**: Quick initialization and mode detection
- **PostToolUse**: Focused validation and rule checking
- **Notification**: Simple notification processing
#### Medium Timeouts (15 seconds)
- **PreToolUse**: Complex MCP routing and decision-making
- **PreCompact**: Compression analysis and strategy selection
- **Stop**: Comprehensive analytics and cleanup
- **SubagentStop**: Delegation analytics and coordination
**Rationale**: Timeouts balance responsiveness with functionality, allowing sufficient time for complex operations while preventing hangs.
## Integration with Hooks
### 1. Hook Lifecycle Integration
The settings enable full lifecycle integration:
```
Session Start → PreToolUse → [Tool Execution] → PostToolUse → ... → Stop
↓
[PreCompact] → [Context Compaction]
↓
[Notification] → [Pattern Updates]
↓
[SubagentStop] → [Task Cleanup]
```
### 2. Configuration Loading Process
1. **Claude Code Startup**: Reads `settings.json` during initialization
2. **Hook Registration**: Registers all 7 hooks with their configurations
3. **Event Binding**: Binds hooks to appropriate Claude Code events
4. **Execution Environment**: Sets up Python execution environment
5. **Timeout Management**: Configures timeout handling for each hook
### 3. Error Handling Integration
The settings enable robust error handling:
- **Process Isolation**: Hook failures don't affect Claude Code operation
- **Timeout Protection**: Prevents runaway hook processes
- **Graceful Degradation**: Claude Code continues even if hooks fail
- **Error Logging**: Hook errors are captured and logged
## Performance Implications
### 1. Execution Overhead
#### Per-Hook Overhead
- **Process Startup**: ~50-100ms per hook execution
- **Python Initialization**: ~100-200ms for first execution per session
- **Import Loading**: ~50-100ms for module imports
- **Configuration Loading**: ~10-50ms for YAML configuration reading
#### Total Session Overhead
- **Session Start**: ~200-500ms (includes project detection and mode activation)
- **Per Tool Use**: ~100-300ms (PreToolUse + PostToolUse)
- **Compression Events**: ~200-400ms (PreCompact execution)
- **Session End**: ~300-600ms (Stop hook analytics and cleanup)
### 2. Timeout Impact
#### Optimal Performance
Most hooks complete well under timeout limits:
- **Average Execution**: 50-200ms per hook
- **95th Percentile**: 200-500ms per hook
- **Timeout Events**: <1% of executions hit timeout limits
#### Timeout Recovery
When timeouts occur:
- **Graceful Fallback**: Claude Code continues without hook completion
- **Error Logging**: Timeout events are logged for analysis
- **Performance Monitoring**: Repeated timeouts trigger performance alerts
### 3. Resource Usage
#### Memory Impact
- **Per Hook**: 10-50MB memory usage during execution
- **Peak Usage**: 100-200MB during complex operations (Stop hook analytics)
- **Cleanup**: Memory released after hook completion
#### CPU Impact
- **Normal Operations**: 5-15% CPU usage during hook execution
- **Complex Analysis**: 20-40% CPU usage for analytics and learning
- **Background Processing**: Minimal CPU usage between hook executions
## Configuration Best Practices
### 1. Timeout Configuration
```json
{
"timeout": 15 // For complex operations
"timeout": 10 // For standard operations
}
```
**Recommendations**:
- Use 10 seconds for simple validation and processing hooks
- Use 15 seconds for complex analysis and coordination hooks
- Monitor timeout events and adjust if necessary
- Consider environment performance when setting timeouts
### 2. Path Configuration
```json
{
"command": "python3 ~/.claude/hooks/hook_name.py"
}
```
**Best Practices**:
- Always use absolute paths or `~` expansion
- Ensure Python 3 is available in the environment
- Verify hook files have execute permissions
- Test hook execution manually before deployment
### 3. Matcher Configuration
```json
{
"matcher": "*" // Universal application
}
```
**Usage Guidelines**:
- Use `"*"` for comprehensive framework integration
- Consider specific matchers only for specialized use cases
- Test matcher patterns thoroughly before deployment
- Document any non-universal matching decisions
### 4. Error Handling Configuration
```json
{
"type": "command", // Enables process isolation
"timeout": 15 // Prevents hangs
}
```
**Error Resilience**:
- Always use `"command"` type for process isolation
- Set appropriate timeouts to prevent hangs
- Implement error handling within hook Python code
- Monitor hook execution success rates
### Dependencies
- Python 3.7+ installation
- Required Python packages (see hook implementations)
- Read/write access to `~/.claude/hooks/` directory
- Network access for MCP server communication (if used)
## Troubleshooting
### Common Configuration Issues
### Hook Not Executing
- **Check file paths**: Verify scripts exist at specified locations
- **Check permissions**: Ensure scripts are executable
- **Check Python**: Verify Python 3 is available in PATH
- **Check timeouts**: Increase timeout if hooks are timing out
#### Hook Not Executing
- **Check**: File permissions on hook Python files
- **Verify**: Python 3 availability in environment
- **Test**: Manual execution of hook command
- **Debug**: Claude Code hook execution logs
### Performance Issues
- **Timeout Tuning**: Adjust timeout values for your system performance
- **Hook Optimization**: Review hook configuration files for performance settings
- **Parallel Execution**: Some hooks can be optimized for parallel execution
#### Timeout Issues
- **Symptoms**: Hooks frequently timing out
- **Solutions**: Increase timeout values, optimize hook performance
- **Analysis**: Profile hook execution times
- **Prevention**: Monitor hook performance metrics
#### Path Issues
- **Symptoms**: "Command not found" or "File not found" errors
- **Solutions**: Use absolute paths, verify file existence
- **Testing**: Test path resolution in target environment
- **Consistency**: Ensure consistent path format across all hooks
#### Permission Issues
- **Symptoms**: "Permission denied" errors
- **Solutions**: Set execute permissions on hook files
- **Commands**: `chmod +x ~/.claude/hooks/*.py`
- **Verification**: Test file execution permissions
### Performance Troubleshooting
#### Slow Hook Execution
- **Profiling**: Use Python profiling tools on hook code
- **Optimization**: Optimize configuration loading and processing
- **Caching**: Implement caching for repeated operations
- **Monitoring**: Track execution times and identify bottlenecks
#### Resource Usage Issues
- **Memory**: Monitor hook memory usage during execution
- **CPU**: Track CPU usage patterns during hook execution
- **Cleanup**: Ensure proper resource cleanup after hook execution
- **Limits**: Consider resource limits for long-running hooks
### Path Issues
- **Absolute Paths**: Use absolute paths if relative paths cause issues
- **User Directory**: Ensure `~/.claude/hooks/` expands correctly in your environment
- **File Permissions**: Verify both read and execute permissions on hook files
## Related Documentation
- **Hook Implementation**: See individual hook documentation in `/docs/Hooks/`
- **Master Configuration**: Reference `superclaude-config.json.md` for comprehensive settings
- **Claude Code Integration**: Review Claude Code hook system documentation
- **Performance Monitoring**: See performance configuration for optimization strategies
## Version History
- **v1.0.0**: Initial hook settings configuration
- Complete 7-hook lifecycle support
- Universal matching with strategic timeout configuration
- Python 3 execution environment with process isolation
- Error handling and timeout protection
- **Hook Implementation**: Individual hook Python files for specific behavior
- **Configuration Files**: YAML configuration files for hook behavior tuning
- **Installation Guide**: Framework installation and setup documentation