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
hooks	object	yes	Event-keyed hooks configuration
description	string	no	Optional description of the hook 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, mcp_tool, 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)
server	string	no	MCP server name (when type is mcp_tool); server must already be connected
tool	string	no	Tool name on the MCP server (when type is mcp_tool)
input	object	no	Arguments passed to the tool (when type is mcp_tool); supports ${path} substitution
prompt	string	no	Prompt text. Required when type is prompt or agent — an agent hook is driven by prompt, not by an agent field
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)
if	string	no	Conditional hook filter
args	string[]	no	Direct executable arguments; bypasses shell interpretation
asyncRewake	boolean	no	Wake Claude after an asynchronous hook
shell	string	no	Shell form: bash or powershell

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."
          }
        ]
      }
    ]
  }
}