Hooks

A hook is a small action that Claude Code runs by itself at a fixed point in a session. The point can be before a tool runs, when you send a prompt, or when the session ends. A hook can block a risky command, add context, or run a check every time. A prompt to Claude cannot promise that, but a hook can.

Claude Code 2.1.312 has 33 hook events. The official docs and the program list the same 33 names. Each hook uses one of 5 handler types: command, http, mcp_tool, prompt, or agent.

Example

This hook blocks every git push that Claude tries to run.

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push *)",
            "command": ".claude/hooks/no-push.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

.claude/hooks/no-push.sh

#!/bin/bash
echo "Pushing is not allowed in this project." >&2
exit 2

Exit code 2 blocks the call. The text on stderr goes back to Claude as the reason.

Configuration Shape

A hook config has three levels.

1. The event name, such as PreToolUse.
2. A matcher group. It has an optional matcher that picks when the group runs.
3. The hooks array. Each entry is a handler that does the work.

Settings files, a plugin hooks/hooks.json (wrapped in a top-level hooks key), and skill and subagent frontmatter all use the same shape.

All matching handlers of an event run in parallel. If a settings file defines the same handler twice, Claude Code runs it once. A copy from a plugin or a skill stays separate.

Where Hooks Are Defined

Place	Status	What it does	Notes
~/.claude/settings.json	Documented: An official docs page names this item.	User hooks for all projects.	Merged with the other levels. Not shared.
.claude/settings.json	Documented: An official docs page names this item.	Project hooks.	Merged. Waits for you to accept the workspace trust dialog. You can commit it.
.claude/settings.local.json	Documented: An official docs page names this item.	Local project hooks.	Merged. Not shared.
Managed policy settings	Documented: An official docs page names this item.	Organization hooks.	disableAllHooks set below the managed level cannot disable them.
--settings '{...}' flag	Documented: An official docs page names this item.	Hooks for one run.	The program calls this source flagSettings. It can set disableAllHooks.
Plugin hooks/hooks.json	Documented: An official docs page names this item.	Plugin hooks.	Active while the plugin is on.
Plugin manifest key hooks	Documented: An official docs page names this item.	A path, an inline object, or an array.	Merged with hooks/hooks.json. See Plugin Manifest Reference.
Skill frontmatter hooks	Documented: An official docs page names this item.	Skill hooks.	Claude Code registers them when the skill runs and keeps them for the session. once works only here.
Subagent frontmatter hooks	Documented: An official docs page names this item.	Hooks that run only while that subagent runs.	Stop becomes SubagentStop. Claude Code ignores them for plugin subagents. See Subagent Frontmatter.
Mod on("classic.<Event>")	Documented: An official docs page names this item.	A function hook on a classic event.	The chain order is managed hooks, hooks modules, then other settings hooks. See React to Events.
SDK callback hooks	Undocumented: Only the program shows this item. It can change without notice.	Handler type callback.	An Agent SDK host sets it. A callback that reaches its timeout on PreToolUse or UserPromptSubmit blocks.

How It Works

When something happens, Claude Code finds every hook for that event. It filters them with the matcher and the optional if rule. Then it runs the remaining hooks in parallel. It merges their answers.

Each handler gets a JSON description of the event. A command hook reads it on stdin. An HTTP hook gets it as the POST body. A handler answers with an exit code, or with exit 0 and a JSON object. Input and Output lists the fields.

note

A mod is a hook that runs as a JavaScript function inside Claude Code. This section does not cover mods. See the Mod API section of this site.

Pages in This Section

Page	Content
Configuration	Matchers, the if filter, timeouts, failure handling, environment variables, settings keys, trust.
Handlers	The five handler types and their fields.
Events	All 33 events, with their input and output fields.
Input and Output	Common input fields, output fields, decisions, exit codes, HTTP replies.

Related Pages

• Configuration: matchers, timeouts, and trust.
• Agent Loop: where hooks fit in a turn.
• Subagent Frontmatter: the hooks key of an agent file.
• Skill Frontmatter: the hooks key of a skill.

Source: Hooks Reference and the program (the hook schemas and the HookInput types).