claude-mem/docs/reference/claude-code/hooks.md

Claude Code Hooks Configuration Documentation

Source: Official Claude Code Docs v2025

Last Verified: 2025-08-31

Hook Configuration Structure

For Tool-Based Hooks (PreToolUse, PostToolUse)

These hooks use the matcher field to match tool patterns:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "ToolPattern",  // Required for tool hooks
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60000  // Optional, in milliseconds
          }
        ]
      }
    ]
  }
}

For Non-Tool Hooks (PreCompact, SessionStart, etc.)

These hooks DO NOT use matcher/pattern fields:

{
  "hooks": {
    "PreCompact": [
      {
        // NO matcher or pattern field!
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/script.js",
            "timeout": 180000
          }
        ]
      }
    ]
  }
}

Available Hook Events

Tool-Related Hooks (use matcher)

• PreToolUse: Before tool execution
• PostToolUse: After tool execution

System Event Hooks (no matcher)

• PreCompact: Before conversation compaction
• SessionStart: When session begins
• SessionEnd: When session ends (not in official docs)
• UserPromptSubmit: When user submits prompt
• Notification: When Claude needs user input
• Stop: When stop is requested
• SubagentStop: When subagent stop is requested

Hook Payload Structure

Common Fields (all hooks)

{
  "session_id": "string",
  "transcript_path": "string",
  "hook_event_name": "string",
  "cwd": "string"  // Current working directory
}

PreCompact Specific

{
  "hook_event_name": "PreCompact",
  "trigger": "manual" | "auto",
  "custom_instructions": "string"
}

SessionStart Specific

{
  "hook_event_name": "SessionStart",
  "source": "startup" | "compact" | "vscode" | "web"
}

PreToolUse/PostToolUse Specific

{
  "tool_name": "string",
  "tool_input": { /* tool specific */ },
  "tool_response": { /* PostToolUse only */ }
}

Common Configuration Mistakes

\u274c INCORRECT: Using 'pattern' for non-tool hooks

{
  "hooks": {
    "PreCompact": [{
      "pattern": "*",  // \u274c WRONG - non-tool hooks don't use this
      "hooks": [...]
    }]
  }
}

\u2705 CORRECT: No matcher for non-tool hooks

{
  "hooks": {
    "PreCompact": [{
      // No pattern or matcher field
      "hooks": [...]
    }]
  }
}

\u274c INCORRECT: Wrong matcher field name

{
  "hooks": {
    "PreToolUse": [{
      "pattern": "Bash",  // \u274c WRONG field name
      "hooks": [...]
    }]
  }
}

\u2705 CORRECT: Using 'matcher' for tool hooks

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",  // \u2705 Correct field name
      "hooks": [...]
    }]
  }
}

Matcher Patterns for Tool Hooks

• Exact match: "Bash" - matches only Bash tool
• Multiple tools: "Edit|MultiEdit|Write" - matches any of these
• MCP tools: "mcp__memory__.*" - matches all memory server tools
• All tools: "*" - matches everything

Environment Variables

Hooks have access to:

• $CLAUDE_PROJECT_DIR - Project root directory

Settings File Locations

1. User settings: ~/.claude/settings.json
2. Project settings: ./.claude/settings.json
3. Local settings: ./.claude/settings.local.json
4. Managed settings: /Library/Application Support/ClaudeCode/managed-settings.json

References

• Official Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
• Hook Guide: https://docs.anthropic.com/en/docs/claude-code/hooks-guide