claude-hooks

Claude Code Hooks

Guide for creating hooks that execute shell commands or scripts in response to Claude Code events and tool calls.

When to Use This Skill

Activate this skill when:

• Creating event-driven automations
• Implementing custom validation or formatting
• Integrating with external tools and services
• Setting up project-specific workflows
• Responding to tool execution events

What Are Hooks?

Hooks are shell commands that execute automatically in response to specific events:

• Tool Call Hooks: Trigger before/after specific tool calls
• Lifecycle Hooks: Trigger on plugin install/uninstall
• User Prompt Hooks: Trigger when users submit prompts
• Custom Events: Application-specific trigger points

Hook Configuration

Location

Hooks are configured in:

• Plugin: <plugin-root>/.claude-plugin/hooks.json
• User-level: .claude/hooks.json
• Plugin manifest: Inline in plugin.json

File Structure

Standalone hooks.json:

{
  "onToolCall": {
    "Write": {
      "before": ["./hooks/format-check.sh"],
      "after": ["./hooks/lint.sh"]
    },
    "Bash": {
      "before": ["./hooks/validate-command.sh"]
    }
  },
  "onInstall": ["./hooks/setup.sh"],
  "onUninstall": ["./hooks/cleanup.sh"],
  "onUserPromptSubmit": ["./hooks/log-prompt.sh"]
}

Inline in plugin.json:

{
  "hooks": {
    "onToolCall": {
      "Write": {
        "after": ["prettier --write {{file_path}}"]
      }
    }
  }
}

Hook Types

Tool Call Hooks

Execute before or after specific tool calls.

Available Tools:

• Read, Write, Edit, MultiEdit
• Bash, BashOutput
• Glob, Grep
• Task, Skill, SlashCommand
• TodoWrite
• WebFetch, WebSearch
• AskUserQuestion

Example:

{
  "onToolCall": {
    "Write": {
      "before": [
        "echo 'Writing file: {{file_path}}'",
        "./hooks/backup.sh {{file_path}}"
      ],
      "after": [
        "prettier --write {{file_path}}",
        "git add {{file_path}}"
      ]
    },
    "Edit": {
      "after": ["eslint --fix {{file_path}}"]
    }
  }
}

Lifecycle Hooks

Execute during plugin installation/uninstallation.

{
  "onInstall": [
    "./hooks/setup-dependencies.sh",
    "npm install",
    "echo 'Plugin installed successfully'"
  ],
  "onUninstall": [
    "./hooks/cleanup.sh",
    "echo 'Plugin uninstalled'"
  ]
}

User Prompt Submit Hook

Execute when user submits a prompt:

{
  "onUserPromptSubmit": [
    "./hooks/log-interaction.sh '{{prompt}}'",
    "./hooks/check-context.sh"
  ]
}

Hook Variables

Hooks have access to context-specific variables using {{variable}} syntax.

Tool Call Variables

Different tools provide different variables:

Write Tool:

• {{file_path}}: Path to file being written
• {{content}}: Content being written (before hooks only)

Edit Tool:

• {{file_path}}: Path to file being edited
• {{old_string}}: String being replaced
• {{new_string}}: Replacement string

Bash Tool:

• {{command}}: Command being executed

Read Tool:

• {{file_path}}: Path to file being read

Global Variables

Available in all hooks:

• {{cwd}}: Current working directory
• {{timestamp}}: Current Unix timestamp
• {{user}}: Current user
• {{plugin_root}}: Plugin installation directory

User Prompt Variables

• {{prompt}}: User's submitted prompt text

Hook Examples

Auto-Format on Write

{
  "onToolCall": {
    "Write": {
      "after": [
        "prettier --write {{file_path}}",
        "eslint --fix {{file_path}}"
      ]
    }
  }
}

Pre-Commit Validation

{
  "onToolCall": {
    "Bash": {
      "before": ["./hooks/validate-git-command.sh '{{command}}'"]
    }
  }
}

validate-git-command.sh:

#!/bin/bash

COMMAND="$1"

# Block force push to main/master
if [[ "$COMMAND" =~ "git push --force" ]] && [[ "$COMMAND" =~ "main|master" ]]; then
  echo "ERROR: Force push to main/master is not allowed"
  exit 1
fi

exit 0

Automatic Backups

{
  "onToolCall": {
    "Write": {
      "before": ["cp {{file_path}} {{file_path}}.backup"]
    },
    "Edit": {
      "before": ["cp {{file_path}} {{file_path}}.backup"]
    }
  }
}

Logging and Analytics

{
  "onToolCall": {
    "Write": {
      "after": ["./hooks/log-file-change.sh {{file_path}}"]
    }
  },
  "onUserPromptSubmit": ["./hooks/log-prompt.sh '{{prompt}}'"]
}

log-file-change.sh:

#!/bin/bash

FILE="$1"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

echo "$TIMESTAMP - Modified: $FILE" >> .claude/file-changes.log

Integration with External Tools

{
  "onToolCall": {
    "Write": {
      "after": [
        "notify-send 'File Updated' 'Modified {{file_path}}'",
        "curl -X POST https://api.example.com/notify -d 'file={{file_path}}'"
      ]
    }
  }
}

Hook Execution

Execution Order

Multiple hooks execute in array order:

{
  "onToolCall": {
    "Write": {
      "after": [
        "echo 'Step 1'",  // Runs first
        "echo 'Step 2'",  // Runs second
        "echo 'Step 3'"   // Runs third
      ]
    }
  }
}

Exit Codes

Before Hooks:

• Exit code 0: Continue with tool execution
• Exit code non-zero: Block tool execution, show error to user

After Hooks:

• Exit codes are logged but don't affect tool execution
• Tool has already completed

Error Handling

#!/bin/bash

# Before hook - blocks tool on error
if [[ ! -f "$1" ]]; then
  echo "ERROR: File does not exist"
  exit 1  # Blocks tool execution
fi

# Validation passed
exit 0

Best Practices

Keep Hooks Fast

Hooks block execution - keep them lightweight:

{
  "onToolCall": {
    "Write": {
      // ✅ Fast linter
      "after": ["eslint --fix {{file_path}}"]

      // ❌ Slow test suite
      // "after": ["npm test"]
    }
  }
}

Use Absolute Paths

Reference scripts with paths relative to plugin:

{
  "onInstall": ["${CLAUDE_PLUGIN_ROOT}/hooks/setup.sh"]
}

Validate Input

Always validate hook variables:

#!/bin/bash

FILE="$1"

if [[ -z "$FILE" ]]; then
  echo "ERROR: No file path provided"
  exit 1
fi

if [[ ! -f "$FILE" ]]; then
  echo "ERROR: File does not exist: $FILE"
  exit 1
fi

Provide Clear Feedback

#!/bin/bash

echo "Running pre-commit checks..."

if ! npm run lint; then
  echo "❌ Linting failed. Please fix errors before committing."
  exit 1
fi

echo "✅ All checks passed"
exit 0

Handle Edge Cases

#!/bin/bash

# Handle files with spaces in names
FILE="$1"

# Validate file type
if [[ ! "$FILE" =~ \.(js|ts|jsx|tsx)$ ]]; then
  # Skip non-JavaScript files silently
  exit 0
fi

# Run formatter
prettier --write "$FILE"

Security Considerations

Validate Commands

Before hooks can block dangerous operations:

{
  "onToolCall": {
    "Bash": {
      "before": ["./hooks/validate-command.sh '{{command}}'"]
    }
  }
}

validate-command.sh:

#!/bin/bash

COMMAND="$1"

# Block dangerous patterns
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "dd if="
  "mkfs"
  "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if [[ "$COMMAND" =~ $pattern ]]; then
    echo "ERROR: Dangerous command blocked: $pattern"
    exit 1
  fi
done

exit 0

Limit Hook Scope

Only hook necessary tools:

{
  // ✅ Specific tools only
  "onToolCall": {
    "Write": { "after": ["./format.sh {{file_path}}"] }
  }

  // ❌ Don't hook everything unnecessarily
}

Sanitize Variables

#!/bin/bash

# Sanitize file path
FILE=$(realpath "$1")

# Ensure file is within project
if [[ ! "$FILE" =~ ^$(pwd) ]]; then
  echo "ERROR: File outside project directory"
  exit 1
fi

Debugging Hooks

Enable Verbose Output

{
  "onToolCall": {
    "Write": {
      "before": ["set -x; ./hooks/debug.sh {{file_path}}; set +x"]
    }
  }
}

Log Hook Execution

#!/bin/bash

LOG_FILE=".claude/hooks.log"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

echo "$TIMESTAMP - Hook: $0, Args: $@" >> "$LOG_FILE"

# Rest of hook logic...

Test Hooks Manually

# Test hook with sample data
./hooks/format.sh "src/main.js"

# Check exit code
echo $?

Common Hook Patterns

Auto-Format Pipeline

{
  "onToolCall": {
    "Write": {
      "after": [
        "prettier --write {{file_path}}",
        "eslint --fix {{file_path}}"
      ]
    },
    "Edit": {
      "after": [
        "prettier --write {{file_path}}",
        "eslint --fix {{file_path}}"
      ]
    }
  }
}

Test on Write

{
  "onToolCall": {
    "Write": {
      "after": ["./hooks/run-relevant-tests.sh {{file_path}}"]
    }
  }
}

Git Integration

{
  "onToolCall": {
    "Write": {
      "after": ["git add {{file_path}}"]
    },
    "Edit": {
      "after": ["git add {{file_path}}"]
    }
  }
}

Troubleshooting

Hook Not Executing

• Check hook file has execute permissions: chmod +x hooks/script.sh
• Verify path is correct relative to plugin root
• Check JSON syntax in hooks.json
• Look for errors in Claude Code logs

Hook Blocking Tool

• Check exit code of before hooks
• Add debug logging
• Test hook script manually
• Verify validation logic

Variables Not Substituting

• Check variable name spelling: {{file_path}} not {{filepath}}
• Verify variable is available for that tool
• Quote variables in bash: "{{file_path}}"

Templates

Reference templates for common hook configurations:

claude-hooks/
└── templates/
    ├── plugin-hook.md    # Plugin hook configuration example
    └── skill-hook.md     # Skill/subagent frontmatter hooks example

Plugin Hook Template

Example configuration for defining hooks in a plugin's hooks/hooks.json:

• PostToolUse hook with Write|Edit matcher
• Uses ${CLAUDE_PLUGIN_ROOT} for script references
• Includes timeout configuration

Skill Hook Template

Example frontmatter for embedding hooks directly in skills:

• Supported events: PreToolUse, PostToolUse, Stop
• Hooks scoped to component lifecycle
• Runs only when skill/subagent is active

References

For more information:

• Claude Code Hooks Documentation: https://code.claude.com/docs/en/hooks
• Plugin Configuration: https://code.claude.com/docs/en/plugins#hooks