Features · Extend it · since version 1.0.38

Hooks

Run your own shell commands at set moments in a session, so some things always happen.

What it is

A hook is a shell command you register in a settings file. Claude Code runs it at a chosen point, for example before a tool call, after a file edit, or when it needs your input. Because the hook is ordinary code, the result does not depend on the model deciding to do something: the rule is applied every time.

Why it matters

  • Rules that always applyA hook that runs before a tool call can stop it, so a project rule such as "never delete these files" is enforced instead of suggested.
  • Less repeated workFormat a file after each edit or run a check when a task ends, without asking for it each time.
  • Know when you are neededA notification hook can alert you when Claude Code is waiting for your input.

How it works

  1. Add a hooks block to a settings file, such as ~/.claude/settings.json.
  2. Pick the event to react to (for example PreToolUse or Notification) and, where it applies, a matcher such as the tool name.
  3. When the event happens, Claude Code runs your command and passes it details of the event as JSON on standard input.
  4. The exit code decides what happens next: 0 lets the action continue, and 2 blocks it on events that can be blocked.
  5. When a hook blocks an action, what it wrote to standard error is the reason Claude receives.

Hands-on example coming

This feature has no reviewed example yet. The official documentation below has the details.

Update history

  1. Version 1.0.38 · Jun 30, 2025

    Introduced Hooks were released.

Official documentation