Skip to main content

Hooks

Hooks are a new mechanic introduced to Claude Code to allow deterministic responses based on a given event such as tool executions, file changes, or deployment activities.

Real-World Implementation​

I have been experimenting with simple use cases for how they can be used to improve the reliability of my existing workflows such as running various pre/post deploy related activities before deploying the ClaudeLog website live.

When you update a website online there are various SEO related activities which must be performed such as:

  • Deploying your sitemap to various web master tools
  • Checking build process has not generated invalid JSON schemas (different web masters are surprisingly sensitive)
  • Validating URLs are all live and well formed

These were simple low hanging fruit which Claude suggested for me to explore implementing into my workflow based on my existing deployment pipeline.

The Scoping Challenge​

Interestingly I found the fiddliest bit was scoping the activation requirements such that they do not activate too early.

Badly Scoped Hook Example​

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/expensive-validation.sh"
          }
        ]
      }
    ]
  }
}

This fires on ANY bash command, running expensive validation even for simple ls or pwd commands

Better Scoped Hook Example - Smart Dispatcher Pattern​

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/smart-hook-dispatcher.sh"
          }
        ]
      }
    ]
  }
}

Smart Dispatcher Script:

#!/bin/bash
# Read JSON input from Claude Code
json_input=$(cat)
command=$(echo "$json_input" | jq -r '.tool_input.command // empty')

# Exit early if no command
if [ -z "$command" ]; then
    exit 0
fi

# Scope to specific commands only
if echo "$command" | grep -q "npm run deploy"; then
    echo "🚀 Running pre-deployment validation..."
    ./scripts/pre-deployment-checks.sh <<< "$json_input"
fi

if echo "$command" | grep -q "npm run build"; then
    echo "🔧 Running build validation..."
    ./scripts/build-validator.sh <<< "$json_input"
fi

This intelligently routes commands based on content analysis, only running expensive operations when needed

Finding Hook Opportunities​

To find suggestions for where hooks could be useful within your setup be sure to ask Claude to review your current systems and suggest the benefit of Hooks.

Just beware that if they're unnecessarily firing you will have an extremely slowed down Agent (thankfully it is not costing you tokens though).

Available Triggers​

  • PreToolUse - Before tool execution
  • PostToolUse - After tool completion
  • Stop - When Claude Code agent finishes responding

Best Practices​

  • Smart dispatching - Use single entry point with intelligent command routing to avoid performance penalties
  • Exit code checking - Validate successful command execution in PostToolUse hooks (.tool_response.exit_code only available after execution)
  • Parallel execution - Run independent validations concurrently with & and wait for faster processing
  • JSON input parsing - Extract command details with jq -r '.tool_input.command // empty' (fallback handles missing fields gracefully)
  • Performance monitoring - Track hook execution time and cache results to identify bottlenecks
  • Error handling - Graceful failure for non-critical hooks prevents workflow interruption
  • Scope precisely - Target specific commands rather than broad tool categories to maintain responsiveness

See Also: Configuration|What is Hooks in Claude Code

Last updated on