← Claude Code, start to finish
Claude Code

Hooks — Make Claude Code Run Your Rules Every Time

28 Jul 2026·5 min read

In the last post we looked at subagents — separate helpers that run a task in their own context and report back. Today we cover the other Core Building Block: hooks. A subagent is extra hands. A hook is a rule that fires on its own — the difference between hoping Claude does something and making sure it always happens.

What a hook actually is

Straight from the official docs: hooks are user-defined shell commands that run at specific points in the Claude Code lifecycle. They give deterministic control — meaning they run every time, instead of relying on the model to choose to run them. CLAUDE.md is guidance the model usually follows but can skip. A hook is not guidance: when the event fires, the command runs.

The lifecycle events you will use

  • SessionStart — when a session begins or resumes
  • UserPromptSubmit — when you submit a prompt, before Claude reads it
  • PreToolUse — before a tool call runs; it can block the call
  • PostToolUse — after a tool call succeeds (great for auto-format)
  • Stop — when Claude finishes responding
  • SessionEnd — when the session ends

Auto-format after every edit

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r \".tool_input.file_path\" | xargs npx prettier --write" }
        ]
      }
    ]
  }
}
PostToolUse with an Edit or Write matcher formats every file Claude edits — automatically.

Block a tool before it runs

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r ".tool_input.command")

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2
  exit 2
fi
exit 0
A PreToolUse hook: exit code 2 blocks the call and sends the reason back to Claude.
Guidance vs guaranteeThis is the whole point of hooks. CLAUDE.md asks nicely; a hook enforces. When rules disagree, deny always wins over allow — and your permission deny rules are still evaluated no matter what a hook returns. So put must-happen work in a hook, not in a paragraph of instructions.

You put hooks in a settings file. Project hooks live in .claude/settings.json and can be committed so your whole team gets them. Personal hooks live in ~/.claude/settings.json for every project on your machine. Run /hooks inside Claude Code to see everything configured — or just describe the hook you want and let Claude write it.

Try it: add an auto-format hook

Enough theory — let us build a real one in a minute. This hook runs Prettier on every file Claude edits, so your formatting stays clean without you ever asking. It is a PostToolUse hook, matched to the Edit and Write tools. Follow these steps in your own project.

  • Open .claude/settings.json in your project root. If the file is not there, create it.
  • Add the hooks block below — a PostToolUse handler with the matcher Edit|Write. If a hooks key already exists, add PostToolUse inside it — do not replace the whole object.
  • Save the file. Claude Code picks up the change on its own within a few seconds.
  • Type /hooks to confirm it registered — you will see PostToolUse in the list with your command under it. Then ask Claude to edit any file.
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r \".tool_input.file_path\" | xargs npx prettier --write" }
        ]
      }
    ]
  }
}
Paste this into .claude/settings.json. The matcher fires only after Edit or Write; jq pulls the edited file path and passes it to Prettier.

Here is what you will see: every time Claude finishes an Edit or a Write, the file is formatted automatically — no reminders, no manual prettier run. The tool call succeeds first, then the hook fires on that file path and Prettier rewrites it in place. Deterministic, every single time.

One more thing worth knowing: swap PostToolUse for PreToolUse and an exit code 2 from your script blocks the tool before it runs — that is how you stop an edit instead of just cleaning up after it.

Next post: managing context and cost — /clear, /compact, and prompt caching.

Hooks — Make Claude Code Run Your Rules Every Time · Ali Huzaifa