Claude Code Hooks

Overview

Create and configure Claude Code hooks to automate workflows, validate inputs, add context, and customize behavior across different events in the Claude Code lifecycle.

When to Use This Skill

Use this skill when users request:

• Creating hooks for any event (PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact, Notification, PermissionRequest)
• Setting up automation for tool usage validation or formatting
• Adding session context at startup
• Validating or blocking prompts
• Controlling when Claude should continue or stop
• Auto-approving or denying permissions
• Setting up notifications

Pre-requisite: Fetch Latest Documentation

MANDATORY FIRST STEP: Before creating any hook, fetch the latest hooks documentation:

WebFetch: https://code.claude.com/docs/en/hooks
Prompt: "Extract the complete hooks reference documentation including all hook events, input/output formats, configuration structure, and examples."

This ensures access to the most current hook events, JSON schemas, and best practices.

Hook Creation Workflow

1. Understand User Requirements

Ask clarifying questions:

• What event should trigger the hook? (PreToolUse, PostToolUse, UserPromptSubmit, etc.)
• What tools should be matched? (Bash, Write, Edit, specific MCP tools, etc.)
• What action should the hook perform? (Validate, format, add context, block, etc.)
• Where should the hook be configured? (User settings ~/.claude/settings.json or project settings .claude/settings.json)

2. Determine Hook Type

Command-based hooks (type: "command"):

• Fast, deterministic validation
• File operations, linting, formatting
• Simple rule-based decisions
• Examples: Bash command validation, code formatting, git checks

Prompt-based hooks (type: "prompt"):

• Context-aware, intelligent decisions using LLM
• Complex evaluation requiring natural language understanding
• Supported for: Stop, SubagentStop, UserPromptSubmit, PreToolUse
• Examples: Task completion checking, security policy evaluation

3. Create Hook Script or Prompt

For command-based hooks, create a script that:

1. Reads JSON input from stdin
2. Validates/processes the input
3. Returns appropriate exit code:
   • 0 = Success (stdout shown to user, or added to context for UserPromptSubmit/SessionStart)
   • 2 = Blocking error (stderr fed back to Claude)
   • Other = Non-blocking error (stderr shown to user)
4. Optionally returns JSON for advanced control

For prompt-based hooks, craft a prompt that:

1. Uses $ARGUMENTS placeholder for hook input
2. Clearly states evaluation criteria
3. Expects JSON response: {"decision": "approve"|"block", "reason": "..."}

4. Configure in Settings

Add hook configuration to appropriate settings file:

• User-wide: ~/.claude/settings.json
• Project-specific: .claude/settings.json
• Local (not committed): .claude/settings.local.json

5. Test and Iterate

1. Verify hook registration with /hooks command
2. Test with relevant tool calls or prompts
3. Use claude --debug to see execution details
4. Refine based on results

Common Hook Patterns

PreToolUse: Bash Command Validation

Use case: Enforce best practices for bash commands (use rg instead of grep, fd instead of find)

Script: Reference scripts/bash_command_validator.py and customize validation rules.

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash_validator.py"
          }
        ]
      }
    ]
  }
}

PostToolUse: Code Formatting

Use case: Automatically format code after file edits

Script: Reference scripts/code_formatter.py and customize for project formatters.

Configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

SessionStart: Load Development Context

Use case: Add git status, recent commits, and environment setup at session start

Script: Reference scripts/session_context_loader.sh and customize for project needs.

Configuration:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/load_context.sh"
          }
        ]
      }
    ]
  }
}

UserPromptSubmit: Validate and Add Context

Use case: Block prompts with secrets, add current timestamp

Script: Reference scripts/prompt_validator.py and customize validation patterns.

Configuration:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate_prompt.py"
          }
        ]
      }
    ]
  }
}

Stop: Intelligent Continuation (Prompt-based)

Use case: Use LLM to decide if Claude should continue working

Configuration:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS\n\nCheck if:\n1. All user tasks are complete\n2. Any errors need addressing\n3. Follow-up work is needed\n\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

PermissionRequest: Auto-Approve Safe Operations

Use case: Automatically approve read operations for documentation files

Script example:

#!/usr/bin/env python3
import json
import sys

input_data = json.load(sys.stdin)
tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

if tool_name == "Read" and file_path.endswith((".md", ".txt", ".json")):
    output = {
        "hookSpecificOutput": {
            "hookEventName": "PermissionRequest",
            "decision": {
                "behavior": "allow"
            }
        }
    }
    print(json.dumps(output))
    sys.exit(0)

# Let normal permission flow proceed
sys.exit(0)

Hook Input/Output Reference

Common Input Fields (All Hooks)

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "string",
  "hook_event_name": "string"
}

Event-Specific Fields

Consult the fetched documentation for complete schemas for each event type (PreToolUse, PostToolUse, UserPromptSubmit, etc.).

JSON Output Schema

Common fields:

{
  "continue": true,
  "stopReason": "string",
  "suppressOutput": true,
  "systemMessage": "string"
}

Event-specific hookSpecificOutput: See fetched documentation for each event type.

Working with MCP Tools

MCP tools follow the pattern mcp__<server>__<tool>:

• mcp__memory__create_entities
• mcp__filesystem__read_file
• mcp__github__search_repositories

Example matcher: "matcher": "mcp__memory__.*" to match all memory server tools.

Security Best Practices

1. Validate inputs: Never trust hook input data blindly
2. Quote variables: Use "$VAR" not $VAR in shell scripts
3. Block path traversal: Check for .. in file paths
4. Use absolute paths: Reference scripts with $CLAUDE_PROJECT_DIR
5. Skip sensitive files: Avoid processing .env, .git/, keys, credentials
6. Set timeouts: Prevent hooks from hanging indefinitely
7. Test in safe environment: Verify hooks before production use

Environment Variables

• $CLAUDE_PROJECT_DIR – Project root directory (all hooks)
• $CLAUDE_ENV_FILE – File for persisting env vars (SessionStart only)
• $CLAUDE_CODE_REMOTE – “true” in web environment, empty in CLI

Debugging Hooks

1. Check registration: Run /hooks command
2. Verify syntax: Ensure JSON is valid
3. Test commands manually: Run hook scripts directly with sample input
4. Check permissions: Ensure scripts are executable (chmod +x)
5. Review logs: Use claude --debug for detailed execution info
6. Validate JSON schemas: Test input/output with sample data

Resources

scripts/

Example hook scripts to customize:

• bash_command_validator.py – Validate and suggest better bash commands
• code_formatter.py – Format code after file edits
• session_context_loader.sh – Load git context and environment at session start
• prompt_validator.py – Validate prompts and add timestamp context

assets/

Template configurations to adapt:

• pretooluse_template.json – PreToolUse hook examples
• posttooluse_template.json – PostToolUse hook examples
• sessionstart_template.json – SessionStart hook examples
• stop_hook_template.json – Prompt-based Stop hook example
• userpromptsubmit_template.json – UserPromptSubmit hook example

Implementation Steps

When implementing a hook for a user:

1. Fetch latest docs from https://code.claude.com/docs/en/hooks
2. Clarify requirements – event type, matcher, action
3. Choose hook type – command-based or prompt-based
4. Create script or prompt using examples as templates
5. Make executable if command-based: chmod +x script.py
6. Add configuration to appropriate settings.json
7. Test with /hooks and claude --debug
8. Document the hook’s purpose and usage for the user