Hooks Configuration

ValidatorHooksOfficial docsHooks

Hooks run commands or prompts in response to Claude Code events. Each key is a hook event name (PascalCase), mapping to an array of matchers.

Fields

Top-level hooks object (standalone hooks.json):

Field	Type	Required	Description
description	string	no	Human-readable description
hooks	object	yes	Event-keyed hooks configuration

Hook Matcher

Each event maps to an array of matcher objects:

Field	Type	Required	Description
matcher	string	no	Pattern to match against (e.g., tool name for PreToolUse)
hooks	object[]	yes	Array of hook handlers

Hook Handler

Field	Type	Required	Description
type	string	yes	command, http, prompt, or agent (valid values)
command	string	no	Shell command (when type is command)
url	string	no	POST endpoint URL (when type is http)
headers	object	no	HTTP headers (when type is http)
allowedEnvVars	string[]	no	Env vars allowed in header interpolation (when type is http)
prompt	string	no	Prompt text (when type is prompt or agent)
agent	string	no	Agent name (when type is agent)
timeout	number	no	Timeout in seconds
statusMessage	string	no	Status message shown during execution
once	boolean	no	Run only once per session
model	string	no	Model override for prompt/agent hooks
async	boolean	no	Run hook asynchronously (non-blocking)

Example

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Bash tool invoked'",
            "timeout": 5000
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review the project README before starting work."
          }
        ]
      }
    ]
  }
}