claude-scripts/hooks/README_HOOKS.md

Claude Code Quality Hooks

Comprehensive quality hooks for Claude Code supporting both PreToolUse (preventive) and PostToolUse (verification) stages to ensure high-quality Python code.

Features

PreToolUse (Preventive)

• Internal Duplicate Detection: Analyzes code blocks within the same file
• Complexity Analysis: Prevents functions with excessive cyclomatic complexity
• Modernization Checks: Ensures code uses modern Python patterns and type hints
• Test Quality Checks: Enforces test-specific rules for files in test directories
• Smart Filtering: Automatically skips test files and fixtures
• Configurable Enforcement: Strict denial, user prompts, or warnings

PostToolUse (Verification)

• Cross-File Duplicate Detection: Finds duplicates across the project
• State Tracking: Compares quality metrics before and after modifications
• Naming Convention Verification: Checks PEP8 compliance for functions and classes
• Quality Delta Reports: Shows improvements vs degradations
• Project Standards Verification: Ensures consistency with codebase

Installation

Quick Setup

# Make setup script executable and run it
chmod +x setup_hook.sh
./setup_hook.sh

Manual Setup

1. Install claude-scripts (required for analysis):

pip install claude-scripts

2. Copy hook configuration to Claude Code settings:

mkdir -p ~/.config/claude
cp claude-code-settings.json ~/.config/claude/settings.json

3. Update paths in settings.json to match your installation location

Hook Versions

Basic Hook (code_quality_guard.py)

• Simple deny/allow decisions
• Fixed thresholds
• Good for enforcing consistent standards

Advanced Hook (code_quality_guard_advanced.py)

• Configurable via environment variables
• Multiple enforcement modes
• Detailed issue reporting

Configuration (Advanced Hook)

Set these environment variables to customize behavior:

Core Settings

Variable	Default	Description
QUALITY_DUP_THRESHOLD	0.7	Similarity threshold for duplicate detection (0.0-1.0)
QUALITY_DUP_ENABLED	true	Enable/disable duplicate checking
QUALITY_COMPLEXITY_THRESHOLD	10	Maximum allowed cyclomatic complexity
QUALITY_COMPLEXITY_ENABLED	true	Enable/disable complexity checking
QUALITY_MODERN_ENABLED	true	Enable/disable modernization checking
QUALITY_REQUIRE_TYPES	true	Require type hints in code
QUALITY_ENFORCEMENT	strict	Enforcement mode: strict/warn/permissive

PostToolUse Features

Variable	Default	Description
QUALITY_STATE_TRACKING	false	Enable quality metrics comparison before/after
QUALITY_CROSS_FILE_CHECK	false	Check for cross-file duplicates
QUALITY_VERIFY_NAMING	true	Verify PEP8 naming conventions
QUALITY_SHOW_SUCCESS	false	Show success messages for clean files

Test Quality Features

Variable	Default	Description
QUALITY_TEST_QUALITY_ENABLED	true	Enable test-specific quality checks for test files

External Context Providers

Variable	Default	Description
QUALITY_CONTEXT7_ENABLED	false	Enable Context7 API for additional context analysis
QUALITY_CONTEXT7_API_KEY	""	API key for Context7 service
QUALITY_FIRECRAWL_ENABLED	false	Enable Firecrawl API for web scraping examples
QUALITY_FIRECRAWL_API_KEY	""	API key for Firecrawl service

Enforcement Modes

• strict: Deny writes with critical issues, prompt for warnings
• warn: Always prompt user to confirm when issues found
• permissive: Allow writes but display warnings

Enhanced Error Messaging

When test quality violations are detected, the hook provides detailed, actionable guidance instead of generic error messages.

Rule-Specific Guidance

Each violation type includes:

• 📋 Problem Description: Clear explanation of what was detected
• ❓ Why It Matters: Educational context about test best practices
• 🛠️ How to Fix It: Step-by-step remediation instructions
• 💡 Examples: Before/after code examples showing the fix
• 🔍 Context: File and function information for easy location

Example Enhanced Message

🚫 Conditional Logic in Test Function

📋 Problem: Test function 'test_user_access' contains conditional statements (if/elif/else).

❓ Why this matters: Tests should be simple assertions that verify specific behavior. Conditionals make tests harder to understand and maintain.

🛠️ How to fix it:
  • Replace conditionals with parameterized test cases
  • Use pytest.mark.parametrize for multiple scenarios
  • Extract conditional logic into helper functions
  • Use assertion libraries like assertpy for complex conditions

💡 Example:
  # ❌ Instead of this:
  def test_user_access():
      user = create_user()
      if user.is_admin:
          assert user.can_access_admin()
      else:
          assert not user.can_access_admin()

  # ✅ Do this:
  @pytest.mark.parametrize('is_admin,can_access', [
      (True, True),
      (False, False)
  ])
  def test_user_access(is_admin, can_access):
      user = create_user(admin=is_admin)
      assert user.can_access_admin() == can_access

🔍 File: test_user.py
📍 Function: test_user_access

External Context Integration

The hook can integrate with external APIs to provide additional context and examples.

Context7 Integration

Provides additional analysis and context for rule violations using advanced language models.

Firecrawl Integration

Scrapes web resources for additional examples, best practices, and community solutions.

Configuration

# Enable external context providers
export QUALITY_CONTEXT7_ENABLED=true
export QUALITY_CONTEXT7_API_KEY="your_context7_api_key"

export QUALITY_FIRECRAWL_ENABLED=true
export QUALITY_FIRECRAWL_API_KEY="your_firecrawl_api_key"

Example Usage

Setting Environment Variables

# In your shell profile (.bashrc, .zshrc, etc.)
export QUALITY_DUP_THRESHOLD=0.8
export QUALITY_COMPLEXITY_THRESHOLD=15
export QUALITY_ENFORCEMENT=warn

Testing the Hook

1. Open Claude Code
2. Try to write Python code with issues:

# This will trigger the duplicate detection
def calculate_total(items):
    total = 0
    for item in items:
        total += item.price
    return total

def compute_sum(products):  # Similar to above
    sum = 0
    for product in products:
        sum += product.price
    return sum

3. The hook will analyze and potentially block the operation

Test Quality Checks

When enabled, the hook performs additional quality checks on test files using Sourcery rules specifically designed for test code:

Test-Specific Rules

• no-conditionals-in-tests: Prevents conditional statements in test functions
• no-loop-in-tests: Prevents loops in test functions
• raise-specific-error: Ensures specific exceptions are raised instead of generic ones
• dont-import-test-modules: Prevents importing test modules in non-test code

Configuration

Test quality checks are controlled by the QUALITY_TEST_QUALITY_ENABLED environment variable:

# Enable test quality checks (default)
export QUALITY_TEST_QUALITY_ENABLED=true

# Disable test quality checks
export QUALITY_TEST_QUALITY_ENABLED=false

File Detection

Test files are automatically detected if they are located in directories containing:

• test/ or tests/ or testing/

Example test file paths:

• tests/test_user.py
• src/tests/test_auth.py
• project/tests/integration/test_api.py

Hook Behavior

What Gets Checked

✅ Python files (.py extension) ✅ New file contents (Write tool) ✅ Modified content (Edit tool) ✅ Multiple edits (MultiEdit tool) ✅ Test files (when test quality checks enabled)

What Gets Skipped

❌ Non-Python files ❌ Test files (when test quality checks disabled) ❌ Fixture files (/fixtures/)

Troubleshooting

Hook Not Triggering

1. Verify settings location:

cat ~/.config/claude/settings.json

2. Check claude-quality is installed:

claude-quality --version

3. Test hook directly:

echo '{"tool_name": "Write", "tool_input": {"file_path": "test.py", "content": "print(1)"}}' | python code_quality_guard.py

Performance Issues

If analysis is slow:

• Increase timeout in hook scripts
• Disable specific checks via environment variables
• Use permissive mode for large files

Disabling the Hook

Remove or rename the settings file:

mv ~/.config/claude/settings.json ~/.config/claude/settings.json.disabled

Integration with CI/CD

These hooks complement CI/CD quality gates:

1. Local Prevention: Hooks prevent low-quality code at write time
2. CI Validation: CI/CD runs same quality checks on commits
3. Consistent Standards: Both use same claude-quality toolkit

Advanced Customization

Custom Skip Patterns

Modify the skip_patterns in QualityConfig:

skip_patterns = [
    'test_', '_test.py', '/tests/',
    '/vendor/', '/third_party/',
    'generated_', '.proto'
]

Custom Quality Rules

Extend the analysis by adding checks:

# In analyze_with_quality_toolkit()
if config.custom_checks_enabled:
    # Add your custom analysis
    cmd = ['your-tool', tmp_path]
    result = subprocess.run(cmd, ...)

Contributing

To improve these hooks:

1. Test changes locally
2. Update both basic and advanced versions
3. Document new configuration options
4. Submit PR with examples

License

Same as claude-scripts project (MIT)