What are Claude Code hooks?

A hook pairs an event with a handler. Events include PreToolUse (before a tool runs), PostToolUse (after it succeeds), UserPromptSubmit, Stop and SessionStart, among many more. Handlers come in five types: command, http, mcp_tool, prompt and agent. On tool events, a matcher picks tool names and an optional if field narrows further with permission-rule syntax such as Bash(git *).

Hooks go under a hooks key in a settings file: ~/.claude/settings.json for all your projects, .claude/settings.json for one project (committed), or .claude/settings.local.json for just you. Plugins, skills and subagents can carry hooks too. A command hook receives the event as JSON on stdin. Exit code 0 means success; exit code 2 blocks the action on events that can block, and the hook’s stderr becomes the reason, which Claude sees on tool events such as PreToolUse; any other code is a non-blocking error.

Put this in .claude/settings.json. The if rule matches npm publish with or without arguments, because a trailing * also matches the bare command, so the hook runs only then. It prints a reason to stderr and exits 2: Claude Code cancels the tool call and shows Claude the reason, so it can take another route.

We ran the command in Bash: it printed the message to stderr and exited with code 2. It needs a POSIX shell such as Bash; on Windows without Git Bash, command hooks run in PowerShell, so write them for that shell.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(npm publish *)",
            "command": "echo 'Releases are published by CI. Do not run npm publish.' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

Instructions in CLAUDE.md are context: Claude usually follows them, but nothing forces it to. Claude Code’s docs point to a PreToolUse hook when an action must be blocked whatever Claude decides. Hooks also take routine chores, such as formatting after each edit, out of the model’s hands.

A hook is code that runs on your machine whenever its event fires. Read the hooks in any repository before you trust its settings.

Hooks vs CLAUDE.md

CLAUDE.md tells Claude what you want, and Claude decides. A hook is run by Claude Code itself on every matching event, whatever Claude decides, and exit code 2 can stop an action outright.

Hooks vs permission rules

A permission rule such as a deny on Bash(npm publish *) also blocks a command, with no script. Use a hook when the decision needs logic, a message to Claude, or a side effect such as logging.

• Free toolTools for Claude Code, MCP and coding agents→Generate CLAUDE.md and AGENTS.md files, build MCP server configs for every editor, and fix Claude Code errors with tested, step-by-step answers.
• Free toolCLAUDE.md Generator→Generate a CLAUDE.md and AGENTS.md for your project.
• Guide · 15 min readClaude Code hooks: a practical guide with examplesHow Claude Code hooks work: every event, the settings.json format, matchers, exit codes and JSON output, with 7 tested examples and fixes for Windows.

• CLAUDE.mdCLAUDE.md is a Markdown file of project instructions that Claude Code loads into context at the start of every session, and AGENTS.md is the open, tool-neutral equivalent read by many coding agents.
• SubagentA subagent is a separate AI worker that a main agent hands a task to, running in its own context window with its own system prompt, tools and model, and returning only its result to the main conversation.
• AI agentAn AI agent is a program in which a language model works towards a goal by repeatedly choosing a tool to call, reading the result and deciding the next step, until the task is done or a stop condition is reached.
• MCPMCP stands for Model Context Protocol, an open standard that lets AI applications such as Claude Code, ChatGPT or VS Code connect to outside tools and data through one common interface.

All 40 terms in the AI glossary