Claude Code hooks: what they are, every event, and examples

Claude Code hooks are commands you configure to run automatically at set points in a session: before a tool runs, after a file is edited, when you submit a prompt, when Claude finishes, and 29 other events. They live in a hooks section of your settings.json, and a hook that exits with code 2 blocks the action and tells Claude why. Anthropic's own framing: an instruction like "never edit .env" in CLAUDE.md or a skill "is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement." Hooks run with your full user permissions, so only use ones you've read.

Key takeaways

• Deterministic: a hook always runs on its event; the model doesn't choose whether to follow it.
• 33 events, from SessionStart to Stop; the ones most people use are PreToolUse, PostToolUse, UserPromptSubmit, Notification and Stop.
• Configured in settings: ~/.claude/settings.json for you, .claude/settings.json for the whole repository.
• Five handler types: a shell command, an HTTP endpoint, an MCP tool, a one-shot model prompt, or an experimental subagent.
• /hooks lists every hook and where it came from; you edit them in the settings files.

What are hooks in Claude Code?

Anthropic describes them as "user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code's lifecycle," giving "deterministic control: certain actions always happen rather than relying on the LLM to choose to run them" (Anthropic).

Each hook gets the event's details as JSON on standard input: the session, the working directory, the permission mode and, for tool events, the tool's name and input. What it does next depends on its exit code:

• 0: carry on. Output in braces is read as JSON.
• 2: block. The message on standard error goes back to Claude as the reason.
• Anything else, 1 included: a non-blocking error; the action goes ahead. Policy hooks must use exit 2.

Which hook events are there?

Anthropic's reference lists 33 as of October 2026. The ones you'll reach for first:

• PreToolUse: before a tool call. Can allow, deny, ask or defer it, and can rewrite its input.
• PostToolUse: after a tool call succeeds, for formatting, linting or tests. The tool has already run.
• UserPromptSubmit: before Claude reads your prompt. Can block it or add context.
• Stop: when Claude finishes responding. Blocking it makes Claude keep working, up to 8 times in a row.
• Notification: when Claude needs your permission or input.
• SessionStart and SessionEnd: load context at the start, clean up at the end.
• PermissionRequest: when a permission prompt would appear; can approve or deny it for you.
• PreCompact and PostCompact, SubagentStart and SubagentStop, PreModelSwitch, ConfigChange, FileChanged and WorktreeCreate cover the rest of the lifecycle.

Anthropic adds events about once a month; at least 19 of today's 33 arrived in 2026.

Where do you configure Claude Code hooks?

• ~/.claude/settings.json: every project on your machine.
• .claude/settings.json: one project, committed so the team shares it.
• .claude/settings.local.json: one project, just for you.
• Managed settings: set by an organization; can't be removed by users.
• Plugins (hooks/hooks.json), and the frontmatter of a skill or subagent, which run only while it's active.

Hooks from all of these are combined, and every matching hook runs. The shape is event, then a matcher, then the handlers:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run lint" }
        ]
      }
    ]
  }
}

A matcher of letters and | is an exact list of tool names; anything else is a regular expression, so Edit.* also matches NotebookEdit. MCP tools are named mcp__server__tool. Command hooks time out after 600 seconds by default, and $CLAUDE_PROJECT_DIR points at the project root.

Claude Code hook examples

Three from Anthropic's hooks guide (Anthropic):

Format every file Claude edits (PostToolUse, in .claude/settings.json): match Edit|Write and run

jq -r '.tool_input.file_path' | xargs npx prettier --write

Protect files Claude must not touch (PreToolUse): match Edit|Write and run a script, "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh, that reads .tool_input.file_path, checks it against .env, package-lock.json and .git/, prints "Blocked" to standard error and exits 2.

Get a desktop notification (Notification, in ~/.claude/settings.json): on macOS, run

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

The guide has Linux (notify-send) and Windows versions too. Matchers such as permission_prompt and idle_prompt narrow it to the moments you care about.

Are Claude Code hooks safe?

Anthropic's warning: "Command hooks execute shell commands with your full user permissions. They can modify, delete, or access any files your user account can access." In an interactive session, hooks wait until you accept the folder's trust dialog. But claude -p and the Agent SDK treat the folder as trusted, so a repository's committed hooks run there; on code you didn't write, start with --bare or --settings '{"disableAllHooks": true}'. Organizations can set allowManagedHooksOnly so only approved hooks run.

Hooks vs skills vs CLAUDE.md

From Anthropic's features overview (Anthropic):

• Hook: "automation that must run on every matching event." Enforcement, and it costs no context unless it returns output.
• Skill: instructions Claude chooses to use, so the "outcome can vary" (Claude Code skills).
• CLAUDE.md: guidance loaded every conversation (CLAUDE.md vs AGENTS.md).
• Subagent: a separate context that returns a summary.

Put the rule in CLAUDE.md, and the guarantee in a hook. More habits in Claude Code best practices.

Does Codex have hooks?

Yes. Codex has 12 lifecycle events, including PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit and Stop, configured in hooks.json or the [hooks] table of config.toml in ~/.codex or the repository's .codex (OpenAI). Codex asks you to review and trust each hook in /hooks before it runs. Its older notify setting only fires when a turn completes.

Sharing hooks with a team

Commit .claude/settings.json and everyone on the repository gets the same hooks; personal ones go in settings.local.json. In Poly (usepoly.co), a team works with one Claude Code or Codex agent in a shared browser room, and any member can approve or stop a change before it happens: a person-sized check alongside the hooks. Free to start. What is Poly?