hook-creator

Hook Creator

Overview

Creates hook configurations that respond to Claude Code events automatically. Hooks enable automation like formatting on save, running tests after edits, or custom session initialization.

When to use: User wants to automate workflows, needs event-driven behavior, or requests hooks for their plugin.

References: Consult plugins/meta/claude-docs/skills/claude-docs/reference/plugins-reference.md for hook specifications and available events.

Hook Structure Requirements

Hooks are defined in hooks/hooks.json with:

1. Event type (SessionStart, PostToolUse, etc.)
2. Matcher (optional, for filtering which tool uses trigger hook)
3. Hook actions (command, validation, notification)
4. Proper use of ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths

Available Events

From official documentation:

• PreToolUse - Before Claude uses any tool
• PostToolUse - After Claude uses any tool
• UserPromptSubmit - When user submits a prompt
• Notification - When Claude Code sends notifications
• Stop - When Claude attempts to stop
• SubagentStop - When subagent attempts to stop
• SessionStart - At session beginning
• SessionEnd - At session end
• PreCompact - Before conversation history compaction

Creation Process

Step 1: Identify Event and Purpose

Ask the user:

• What should happen automatically?
• When should it happen (which event)?
• What tool uses should trigger it (if PostToolUse)?

Step 2: Choose Hook Type

Three hook types:

• command: Execute shell commands/scripts
• validation: Validate file contents or project state
• notification: Send alerts or status updates

Step 3: Write Hook Configuration

Structure for hooks/hooks.json:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName1|ToolName2",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/script.sh"
          }
        ]
      }
    ]
  }
}

Step 4: Create Associated Scripts

If using command hooks:

1. Create script in plugin's scripts/ directory
2. Make executable: chmod +x scripts/script.sh
3. Use ${CLAUDE_PLUGIN_ROOT} for paths

Step 5: Verify Against Official Docs

Check plugins/meta/claude-docs/skills/claude-docs/reference/plugins-reference.md for:

• Current event names
• Hook configuration schema
• Environment variable usage

Key Principles

• Event Selection: Choose most specific event for the need
• Matcher Precision: Use matchers to avoid unnecessary executions
• Script Paths: Always use ${CLAUDE_PLUGIN_ROOT} for portability
• Error Handling: Scripts should handle errors gracefully

Examples

Example 1: Code Formatting Hook

User: "Auto-format code after I edit files"

Hook configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Creates scripts/format-code.sh that runs formatter on modified files.

Example 2: Session Welcome Message

User: "Show a message when Claude starts"

Hook configuration:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Welcome! Plugin loaded successfully.'"
          }
        ]
      }
    ]
  }
}

Simple command hook, no external script needed.

Example 3: Test Runner Hook

User: "Run tests after I modify test files"

Hook configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh"
          }
        ]
      }
    ]
  }
}

Creates scripts/run-tests.sh that detects test file changes and runs relevant tests.