hook-development

Claude Code hooks automate workflows by configuring a valid hooks.json schema to handle PreToolUse, PostToolUse, and SessionStart events. You implement prompt-based or command-based hooks in scripts to validate tool usage and coordinate event responses.

Prompt-based hooks use natural language to guide Claude's behavior dynamically, while command hooks execute deterministic script checks. Both are defined in hooks.json and organized across events to guard, validate, and coordinate tool usage within Claude Code plugins.

Setting up hooks.json requires defining valid hook types for events like PreToolUse and Stop, ensuring portable paths via CLAUDE_PLUGIN_ROOT, and using jq for JSON handling. Scripts are organized in a scripts directory to provide clear exit codes and structured outputs.

Yes, jq is required for JSON handling when building Claude Code hooks. It processes the JSON payloads passed to command-based hooks, enabling scripts to parse event data and return structured outputs with appropriate exit codes for hook results.

Use SessionStart hooks to initialize environment configurations when a session begins, and Stop hooks to execute cleanup or validation when Claude finishes responding. Coordinating these events in hooks.json orchestrates workflows and enforces safety across the session lifecycle.

Hooks may fail to trigger if the hooks.json schema contains invalid types or incorrect paths. Ensure paths use CLAUDE_PLUGIN_ROOT for portability, scripts return proper exit codes, and jq correctly parses the event JSON to generate structured hook results.