---

name: hooks description: | Write effective Claude Code hooks for automation, validation, and workflow control. Use when creating hooks, configuring PreToolUse/PostToolUse events, or automating Claude behavior. Triggers: hooks, PreToolUse, PostToolUse, PermissionRequest, SessionStart, Stop, hook configuration

Claude Code Hooks Developer Guide

What Are Hooks?

Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control over Claude's behavior—ensuring certain actions always happen rather than relying on Claude to choose to do them.

Key Principle: Hooks turn suggestions into automated actions. Instead of asking Claude to format code, a hook makes it happen every time.

---

Quick Reference: Which Hook to Use

For detailed event documentation, see events-reference.md.

---

Hook Configuration Locations

Hooks can be configured in four scopes (highest to lowest priority):

Configuration in settings.json

Copy{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate-bash.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Configuration in Skill Frontmatter

Skills can embed hooks that activate when the skill is used:

Copy---
name: secure-operations
description: Perform operations with security validation
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

---

Hook Types

Command Hooks (Recommended)

Execute shell commands with JSON input via stdin:

Copy{
  "type": "command",
  "command": "python3 ~/.claude/hooks/validate.py",
  "timeout": 60
}

Prompt Hooks

Use LLM evaluation for context-aware decisions:

Copy{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop. Check if tasks are complete.",
  "timeout": 30
}

Supported for: Stop, SubagentStop, UserPromptSubmit, PreToolUse, PermissionRequest

---

Core Patterns

Exit Codes

JSON Output Schema

All hooks can return:

Copy{
  "continue": true,
  "stopReason": "string",
  "suppressOutput": true,
  "systemMessage": "Warning to show user"
}

PreToolUse Permission Control

Copy{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "Auto-approved: safe operation",
    "updatedInput": {
      "command": "modified command"
    }
  }
}

---

Matcher Patterns

Matchers are case-sensitive and support regex:

---

Environment Variables

Available in hook commands:

---

Debugging Hooks

1. View registered hooks: Run /hooks command
2. Test manually: Run hook commands in terminal first
3. Debug mode: Use claude --debug to see execution
4. Check permissions: Ensure scripts are executable (chmod +x)

---

Additional Resources

---

Security Warning

Hooks execute with your user credentials. Always:

• Review hook code before adding
• Test in safe environment first
• Validate and sanitize all inputs
• Use absolute paths in scripts

See security.md for comprehensive security guidance.