---

name: hooks-reference description: Claude Code hooks configuration reference. Use when creating hooks, understanding hook events (PreToolUse, PostToolUse, Stop, SessionStart, etc.), debugging hook behavior, or implementing automation.

Claude Code Hooks Reference

Hooks are user-defined shell commands that execute at various points in Claude Code's lifecycle, providing deterministic control over behavior.

Quick Reference: Hook Events

Hook Configuration Location

Copy~/.claude/settings.json          # User-level (all projects)
.claude/settings.json            # Project-level (team shared)
.claude/settings.local.json      # Project-local (gitignored)

Basic Hook Structure

Copy{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "your-script.sh"
          }
        ]
      }
    ]
  }
}

Matcher Patterns

Hook Types

Command Hook

Copy{
  "type": "command",
  "command": "jq '.tool_input' >> /tmp/log.txt"
}

Prompt Hook

Copy{
  "type": "prompt",
  "prompt": "Review the output: $ARGUMENTS"
}

Agent Hook

Copy{
  "type": "agent",
  "prompt": "Verify the changes meet security requirements"
}

Control Flow via Exit Codes

Hook Output Format (stdout JSON)

Copy{
  "continue": true,
  "decision": "approve",
  "reason": "Looks good",
  "suppressOutput": false
}

Common Patterns

Auto-format on file write

Copy{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "jq -r '.tool_input.file_path' | xargs prettier --write"
    }]
  }]
}

Block sensitive file edits

Copy{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "jq -e '.tool_input.file_path | test(\"\\\\.env|\\\\.git\")' && exit 2 || exit 0"
    }]
  }]
}

Log all Bash commands

Copy{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
    }]
  }]
}

Environment Variables in Hooks

Debugging Hooks

Copy# View loaded hooks
/hooks

# Test hook manually with sample input
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | your-hook.sh

# Check exit code
echo $?

Security Considerations

• Hooks run with your credentials
• Validate all input before use
• Don't log sensitive data
• Use absolute paths for scripts
• Test hooks in isolation first

---

For complete documentation including all event schemas, see:

• hooks-full.md - Complete hooks reference
• hooks-howto.md - Step-by-step tutorials