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