Our review

A guide for developing Claude Code hooks, shell scripts that execute automatically in response to tool calls, notifications, session events, and more.

Strengths

Enables automation of workflows like linting, formatting, notifications, and custom validations.
Supports a wide range of events (PreToolUse, PostToolUse, SessionStart, etc.).
Provides environment variables for flexible integration with the project.
Recommends prompt-based hooks for complex, context-aware logic.

Limitations

Requires a good understanding of event types and execution order.
Command hooks are limited to simple deterministic checks.
Manual handling of timeouts and error states is necessary.

When to use it

When you need to enforce policies, automate repetitive tasks, or integrate external tools into Claude Code workflows.

When not to use it

For simple one-off customizations, directly instructing the agent in the prompt is more straightforward.

Examples

Create a PreToolUse linting hook

Create a hook that runs eslint on any JavaScript file before it is used by Claude. Use PreToolUse event and only trigger when the tool is reading or writing a .js file.

Set up a session start context loader

I want a hook that loads a summary of the current project from a README file every time a new session starts. Use the SessionStart event and store context in an environment variable.

Debug an existing hook

My PostToolUse hook that logs tool calls isn't firing. Check my hook configuration and help me debug the event listener setup.

name: hook-development description: "[Utility] Guide for developing Claude Code hooks - shell commands that execute automatically in response to tool calls and notifications. Use this when users want to create, debug, or optimize hooks for automating workflows like linting, formatting, notifications, or custom validations. Supports PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification events."

Hook Development for Claude Code Plugins

Overview

Hooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.

Hook Types

Prompt-Based Hooks (Recommended)

Use LLM-driven decision making for context-aware validation.

Command Hooks

Execute bash commands for deterministic checks.

Hook Events

| Event | When | Use For | |-------|------|---------| | PreToolUse | Before tool | Validation, modification | | PostToolUse | After tool | Feedback, logging | | UserPromptSubmit | User input | Context, validation | | Stop | Agent stopping | Completeness check | | SubagentStop | Subagent done | Task validation | | SessionStart | Session begins | Context loading | | SessionEnd | Session ends | Cleanup, logging | | PreCompact | Before compact | Preserve context | | Notification | User notified | Logging, reactions |

Environment Variables

$CLAUDE_PROJECT_DIR - Project root path
$CLAUDE_PLUGIN_ROOT - Plugin directory
$CLAUDE_ENV_FILE - SessionStart only: persist env vars here

Best Practices

Use prompt-based hooks for complex logic
Use ${CLAUDE_PLUGIN_ROOT} for portability
Validate all inputs in command hooks
Set appropriate timeouts

Hook Development for Claude Code

Recommended for