pre-post-hooks

Pre/Post Hooks

Claude Code hooks are shell commands that execute automatically in response to tool events. They enable validation, formatting, and guardrails without manual intervention.

When to Use

• User wants to run a command before or after a tool executes
• User asks about PreToolUse, PostToolUse, or Stop hooks
• User wants to add validation gates or blockers
• User needs to configure hooks in settings.json
• User mentions auto-running commands on file edit, git push, or session end

Core Patterns

Hook Types and Lifecycle

PreToolUse  --> Tool Executes --> PostToolUse
                                       |
                                  (session ends)
                                       |
                                     Stop

• PreToolUse: Runs before a tool call. Can block execution by returning a non-zero exit code.
• PostToolUse: Runs after a tool call completes. Used for side effects like formatting or checks.
• Stop: Runs when the agent session ends. Used for final audits or cleanup.

Hook Configuration in settings.json

Hooks live in ~/.claude/settings.json under the hooks key:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "echo 'About to write a file'",
        "description": "Log before file writes"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\"",
        "description": "Auto-format after editing JS/TS files"
      }
    ],
    "Stop": [
      {
        "command": "echo 'Session ended'",
        "description": "Log session end"
      }
    ]
  }
}

Matcher Patterns

The matcher field filters which tool triggers the hook. It matches against tool names:

{
  "matcher": "Edit",
  "command": "..."
}

Common tool names to match:

• Write — file creation
• Edit — file modification
• Bash — shell command execution
• Read — file reading
• Glob — file search
• Grep — content search