hook-creator

Hook Creator

Create Claude Code hooks that execute shell commands at specific lifecycle events.

Hook Creation Workflow

1. Identify the use case - Determine what the hook should accomplish
2. Select the appropriate event - Choose from available hook events (see references/hook-events.md)
3. Design the hook command - Write shell command that processes JSON input from stdin
4. Configure the matcher - Set tool/event filter (use * for all, or specific tool names like Bash, Edit|Write)
5. Choose storage location - User settings (~/.claude/settings.json) or project (.claude/settings.json)
6. Test the hook - Verify behavior with a simple test case

Hook Configuration Structure

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<ToolPattern>",
        "hooks": [
          {
            "type": "command",
            "command": "<shell-command>",
            "once": true
          }
        ]
      }
    ]
  }
}

Hook Types

• type: "command" - Execute shell command (default)
• type: "prompt" - LLM-based evaluation. Supported for: Stop, SubagentStop, UserPromptSubmit, PreToolUse, PermissionRequest

Hook Options

• once - Run only once per session (optional, default: false)

Common Patterns

Reading Input Data

Hooks receive JSON via stdin. Use jq to extract fields:

# Extract tool input field
jq -r '.tool_input.file_path'

# Extract with fallback
jq -r '.tool_input.description // "No description"'

# Conditional processing
jq -r 'if .tool_input.file_path
  then .tool_input.file_path else empty end'

Exit Codes for PreToolUse

• 0 - Allow the tool to proceed
• 2 - Block the tool and provide feedback to Claude

Matcher Patterns

• * - Match all tools
• Bash - Match only Bash tool
• Edit|Write - Match Edit or Write tools
• Read - Match Read tool

Quick Examples

Log all bash commands:

jq -r '"\(.tool_input.command)"' >> ~/.claude/bash-log.txt