Claude Code hooks: run your own scripts on every edit, command and prompt

Instructions in CLAUDE.md are advice: Claude reads them and usually follows them. A hook is not advice. It is a command that Claude Code itself runs at a fixed moment, such as just before Claude runs a tool, just after it edits a file, or when it finishes answering. It runs every time, whatever Claude decides.

Use a hook for anything that must always happen: format each file after an edit, refuse writes to a folder, tell you when Claude is waiting, or put fresh facts into the conversation when a session starts.

How a hook is set up

Hooks go in a settings file under "hooks", in 3 levels: the event (when), a matcher (which tool or case) and the handlers (what runs). This one runs a formatter after every edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh" }
        ]
      }
    ]
  }
}

And the script, .claude/hooks/format.sh, made executable with chmod +x:

#!/bin/bash
# Claude Code sends the tool call as JSON on stdin
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.ts|*.tsx|*.js|*.json|*.css) npx prettier --write "$file" ;;
esac
exit 0

Put it in .claude/settings.json to share it with the team, .claude/settings.local.json for yourself in this project, or ~/.claude/settings.json for every project. Hooks from all the files run together. $CLAUDE_PROJECT_DIR is the project's root, so the script is found wherever Claude happens to be working.

Type /hooks in a session to see every hook that is loaded and where it came from. It only shows them; you change hooks in the files, and Claude Code picks the change up without a restart.

Matchers

The matcher says which cases fire the hook. For tool events it is the tool's name:

• "*", "" or no matcher: every case.
• Plain names such as Bash or Edit|Write: exactly those names.
• Anything with other characters is a regular expression that may match anywhere in the name, so Edit.* also catches NotebookEdit. Write ^Edit$ to be exact, and mcp__github__.* for every tool of one MCP server.

Other events match other things: SessionStart matches how the session began (startup, resume, clear, compact), Notification the kind of notice. Some, such as Stop and UserPromptSubmit, take no matcher and always fire. The if field narrows a handler further with one permission rule, such as "if": "Bash(git push *)", so the script starts only for those commands.

The events you will use most

There are over 30 events in all, for permissions, tasks, worktrees, files changing and more. Search them in the list at the end of this page.

What a hook receives and returns

Claude Code passes the details as JSON on the hook's standard input: the session id, the working folder, the permission mode, the event's name and, for tool events, tool_name and tool_input, such as the file path or the command.

The hook answers with its exit code:

• 0: carry on. For SessionStart and UserPromptSubmit, whatever it prints is added to the conversation for Claude to read.
• 2: stop. What it writes to stderr becomes the reason, which Claude sees. A PreToolUse hook cancels the tool call this way; a Stop hook makes Claude keep working.
• Anything else: an error that is reported and otherwise ignored, and the action goes ahead.

For finer control a hook can print a JSON object instead, for example to deny a tool call with a reason, or to ask you rather than decide.

Example: keep Claude out of a folder

Applied database migrations must never be edited. This PreToolUse hook refuses any edit to db/migrations/:

#!/bin/bash
# .claude/hooks/protect-migrations.sh
file=$(jq -r '.tool_input.file_path // empty')
if [[ "$file" == *"/db/migrations/"* ]]; then
  echo "Applied migrations are read-only. Write a new migration instead." >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-migrations.sh" }
        ]
      }
    ]
  }
}

A deny from PreToolUse holds in every permission mode, even when permissions are skipped. The other way does not work: a hook that allows something cannot override a deny rule. A hook checks only the tool it matches, though, so a determined Bash command could still write the file. For a hard limit, add a deny rule or the sandbox as well.

Example: a notification when Claude is waiting

In ~/.claude/settings.json, so it works in every project (macOS):

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Waiting for you\" with title \"Claude Code\"'" }
        ]
      }
    ]
  }
}

On Linux, notify-send "Claude Code" "Waiting for you" does the same.

Example: facts back after compaction

A summary can drop details. A SessionStart hook with the compact matcher runs right after each CompactionCompactionReplacing the older part of a long conversation with a summary, so an agent can keep working when its context fills up., and what it prints goes back into the conversation:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo 'Use pnpm, not npm.'; git status --short" }
        ]
      }
    ]
  }
}

Things that trip people up

• Several hooks on one event run at the same time, not in order. If any one blocks, the action is blocked, but the others have still run.
• Stop fires every time Claude finishes answering, not only when the whole task is done. A Stop hook that blocks keeps Claude working; after 8 blocks in a row Claude Code overrides it. Check the stop_hook_active field in the input and let Claude stop if it is already true.
• Timeouts: a command hook may take up to 10 minutes by default (30 seconds on UserPromptSubmit). Set "timeout" in seconds for anything slow.
• Not firing? Check /hooks, that the matcher's case matches the tool name, and that the script is executable. Test it by hand: echo '{"tool_input":{"file_path":"db/migrations/1.sql"}}' | .claude/hooks/protect-migrations.sh; echo $?.
• Besides commands, a hook can call a web address ("type": "http"), an MCP tool, or have a Claude model judge the case and answer yes or no ("type": "prompt").

Hooks run your code: check them first

A command hook runs with your full user permissions, not inside Claude's permission rules. A repository's .claude/settings.json can define hooks, so cloning a project and opening Claude Code in it can run its code. In an interactive session, Claude Code holds back a folder's hooks until you trust it. Read the file before you say yes.

Scripts that run claude -p in a repository you did not write should add --bare, which skips hooks and other settings found on disk. In your own hook scripts, put variables in quotes ("$file"), use full paths, and never pass text from the tool call straight to a shell.

"disableAllHooks": true in your settings turns off every hook except those an organization manages.