Claude Code hooks
explained, with a real plugin.

What are Claude Code hooks?

A hook is a handler that runs every time its event fires: before a tool call, after a file edit, when you submit a prompt, when the session ends. A CLAUDE.md instruction is advice Claude may follow; a hook always runs.

Most hooks are shell commands: Claude Code sends the event as JSON on stdin, and the command answers with an exit code and, optionally, JSON on stdout. Other handler types post the event to a URL (http), call an MCP tool, or ask a model or a subagent.

This .claude/settings.json blocks edits to protected files before they happen and runs Prettier on every file Claude writes. Both commands read the event with jq, so it has to be on your PATH:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-files.sh",
            "args": []
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

Where hooks are configured

Hooks sit under the hooks key of a settings file, never in a file of their own: only plugins use a separate hooks/hooks.json. Hooks from every location run, so a project hook adds to yours instead of replacing it. /hooks lists every active hook and where it came from.

Command hooks run with your full user permissions. Settings-file hooks wait for the folder's trust dialog, but claude -p skips it, so read a repository's .claude/settings.json before you script Claude over code you didn't write.

Claude Code hook events and matchers

The hooks reference lists more than 30 events. A matcher picks which occurrences fire a group: the tool name for tool events, the source or reason for session events. Matchers are case-sensitive. One made only of letters, digits, _, -, | and , lists exact names, such as Edit|Write; any other character makes it an unanchored regex, so Edit.* also matches NotebookEdit. MCP tools are named mcp__server__tool, so mcp__github__.* covers one server.

On tool events, a handler's if field filters further with permission-rule syntax, such as Bash(git *) or Edit(*.ts), so the command doesn't even start for other calls.

How a hook allows or blocks

A hook answers with its exit code (the table below) or, for finer control, exits 0 and prints JSON. A PreToolUse hook sets permissionDecision to allow, deny, ask or defer; when hooks disagree, deny wins over defer, ask and allow, and updatedInput replaces the tool's whole input. A deny holds even in bypassPermissions mode, but an allow can't override a deny rule in settings. This output denies the call:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

When a hook fails quietly

Because only exit code 2 blocks, a broken hook stops nothing. One of our repositories runs its formatter in a PostToolUse hook after every Edit and Write; on a laptop without pnpm it failed 124 times in two days (exit code 127, command not found), and Claude carried on each time, so the formatter never ran.

Run a hook's command in your own shell before you commit it, with a sample event on stdin. In a session, /hooks shows whether it loaded, and claude --debug writes each match, exit code and output to ~/.claude/debug/<session-id>.txt.

echo '{"tool_name":"Edit","tool_input":{"file_path":".env"}}' \
  | .claude/hooks/protect-files.sh
echo $?   # 2: blocked

Does Codex have hooks?

Yes, on by default. Codex reads them from a hooks.json or [hooks] tables in config.toml, in ~/.codex or the repository's .codex folder, and a Codex plugin can ship its own. The events mirror Claude Code's: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, the subagent and compaction events, and a few more. A hook you add yourself runs only after you review and trust it in /hooks.

Blocking works the same way: exit code 2 with a reason on stderr, or JSON with permissionDecision set to deny. An ask decision is parsed but not supported yet. Zest's Codex plugin uses two hooks, SessionStart and UserPromptSubmit, to keep its login fresh.

Does Cursor have hooks?

Yes. Cursor reads .cursor/hooks.json in the project and ~/.cursor/hooks.json, plus enterprise and team hooks that take precedence. Its events have their own names: beforeShellExecution, beforeMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, stop, and generic preToolUse and postToolUse.

Exit code 2 blocks here too, and other failures let the action go ahead unless the hook sets failClosed. Cursor also runs the hooks in Claude Code's settings files, mapping their events to its own, while its setting for third-party configs is on, which it is by default. A hook written for Claude Code can then fire in both tools, so test it in each.

Hook examples from a real plugin: Zest

Zest builds AI coding analytics from three hooks: each session's models, tokens, skills, subagents and MCP tools, next to the branch, commits and pull request it touched, shown as Claude Code usage per engineer.

This is the plugin's hooks/hooks.json. PostToolUse has no matcher, so it runs after every tool call. Each hook has a timeout, exits 0 and returns no decision: Zest records, and never blocks or changes what Claude does.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/zest hook session-start",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/zest hook session-end",
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/zest hook incremental",
            "timeout": 15
          }
        ]
      }
    ]
  }
}