---
url: /api/schemas/hooks.md
description: >-
  Schema reference for hooks.json configuration including events, matchers, and
  handler types.
---

# Hooks Configuration

Hooks run commands or prompts in response to Claude Code events. Each key is a [hook event](/api/schemas#hook-events) 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)                   |

## Hook Handler

| Field            | Type     | Required | Description                                                                                                           |
| ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `type`           | string   | yes      | `command`, `http`, `mcp_tool`, `prompt`, or `agent` ([valid values](/api/schemas#hook-types))                         |
| `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

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