SuperClaude/Framework-Hooks/docs/Configuration/settings.json.md

Hook Settings Configuration (settings.json)

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.

Purpose and Role

The hook settings configuration serves as:

• Hook Registration: Registers all 7 SuperClaude hooks with Claude Code
• 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

File Structure and Organization

1. Hook Registration Pattern

The configuration follows Claude Code's hook registration format:

{
  "hooks": {
    "HookName": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/hook_file.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

2. Hook Definitions

SessionStart Hook

"SessionStart": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/session_start.py",
        "timeout": 10
      }
    ]
  }
]

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

PreToolUse Hook

"PreToolUse": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/pre_tool_use.py",
        "timeout": 15
      }
    ]
  }
]

Purpose: Intelligent tool routing and MCP server selection before tool execution Timeout: 15 seconds (allows for MCP coordination and decision-making) Execution: Runs before every tool use operation Implementation: /pre_tool_use.py handles orchestrator logic, MCP routing, and performance optimization

PostToolUse Hook

"PostToolUse": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/post_tool_use.py",
        "timeout": 10
      }
    ]
  }
]

Purpose: Quality validation, rules compliance, and effectiveness measurement after tool execution Timeout: 10 seconds (sufficient for validation cycles) Execution: Runs after every tool use operation Implementation: /post_tool_use.py handles quality gates, rule validation, and learning integration

PreCompact Hook

"PreCompact": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/pre_compact.py",
        "timeout": 15
      }
    ]
  }
]

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

Notification Hook

"Notification": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/notification.py",
        "timeout": 10
      }
    ]
  }
]

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

Stop Hook

"Stop": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/stop.py",
        "timeout": 15
      }
    ]
  }
]

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

SubagentStop Hook

"SubagentStop": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/subagent_stop.py",
        "timeout": 15
      }
    ]
  }
]

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

Key Configuration Sections

1. Universal Matching Pattern

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

2. Command Type Specification

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

3. Python Path Configuration

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

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

{
  "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

{
  "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

{
  "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

{
  "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

Troubleshooting

Common Configuration Issues

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

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

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