Hook Development Utility Scripts

These scripts help validate, test, and lint hook implementations before deployment.

validate-hook-schema.sh

Validates hooks.json configuration files for correct structure and common issues.

Usage:

./validate-hook-schema.sh path/to/hooks.json

Checks:

• Valid JSON syntax
• Required fields present
• Valid hook event names
• Proper hook types (command/prompt)
• Timeout values in valid ranges
• Hardcoded path detection
• Prompt hook event compatibility

Example:

cd my-plugin
./validate-hook-schema.sh hooks/hooks.json

test-hook.sh

Tests individual hook scripts with sample input before deploying to Claude Code.

Usage:

./test-hook.sh [options] <hook-script> <test-input.json>

Options:

• -v, --verbose - Show detailed execution information
• -t, --timeout N - Set timeout in seconds (default: 60)
• --create-sample <event-type> - Generate sample test input

Example:

# Create sample test input
./test-hook.sh --create-sample PreToolUse > test-input.json

# Test a hook script
./test-hook.sh my-hook.sh test-input.json

# Test with verbose output and custom timeout
./test-hook.sh -v -t 30 my-hook.sh test-input.json

Features:

• Sets up proper environment variables (CLAUDE_PROJECT_DIR, CLAUDE_PLUGIN_ROOT)
• Measures execution time
• Validates output JSON
• Shows exit codes and their meanings
• Captures environment file output

hook-linter.sh

Checks hook scripts for common issues and best practices violations.

Usage:

./hook-linter.sh <hook-script.sh> [hook-script2.sh ...]

Checks:

• Shebang presence
• set -euo pipefail usage
• Stdin input reading
• Proper error handling
• Variable quoting (injection prevention)
• Exit code usage
• Hardcoded paths
• Long-running code detection
• Error output to stderr
• Input validation

Example:

# Lint single script
./hook-linter.sh ../examples/validate-write.sh

# Lint multiple scr