Your Prompt Rules Are Just Suggestions: Claude Code Hooks Auto-Format Every Edit and Block Dangerous Commands (2-Minute Setup)

Last Verified: October 25, 2026 — commands checked against live GitHub sources, plus a real hook rewrite measured on our own machine

You told Claude Code “always run the formatter after editing” and “never run rm -rf”. It listened, until it didn’t. A rule in a prompt is a request — it can be forgotten, skipped, or missed after a context compaction.

A hook is not a request. It’s a shell command that runs automatically at a specific point in the agent’s workflow, and it can actually block an action before it happens. This guide covers real, practical hook setups you can have running in about 2 minutes, not just the concept.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Add a PostToolUse hook to this project's .claude/settings.json that runs [DESCRIBE WHAT YOU WANT, e.g. "prettier --write on every file the Write or Edit tool touches" or "eslint on every .ts file after it's edited"]. Then do the following to prove it actually works, not just that the JSON is valid:

1. Show me the exact hooks block you added.
2. Make a small test edit to a real file in this project.
3. Show me the hook actually ran (its output or the resulting file change) as a direct result of that edit.
4. If it didn't fire, tell me why (wrong matcher, wrong event, syntax error in settings.json) instead of claiming it worked.

What You’ll Need

Step-by-Step Setup

Prefer to build your own hook from scratch instead of the starter above? Here’s how the pieces fit together.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "/path/to/block-dangerous-commands.sh" }
        ]
      }
    ]
  }
}

What Each Piece Does

Verify a Hook Actually Fires

Config validity is not proof it works. Trigger the exact tool the matcher targets and confirm the side effect happened:

echo "test" >> some-file.txt && cat some-file.txt

If nothing happens, check three things in order: the matcher’s exact casing, whether you restarted the session after editing settings.json, and whether the command itself runs correctly when you paste it into a terminal directly.

Common Mistakes to Avoid

• Reading the file path from an environment variable. Claude Code passes the tool call as JSON on stdin; extract the path with jq -r '.tool_input.file_path'.
• Wrong matcher casing. Tool names are case-sensitive: Write matches, write does not.
• Expecting exit code 1 to block anything. Only exit code 2 blocks a PreToolUse call — any other non-zero code is just logged as an error while the tool still proceeds.
• Assuming PostToolUse hooks run in order. Multiple hooks matching the same event run simultaneously, not sequentially — don’t rely on one finishing before another starts.
• Forgetting subagents inherit hooks too. If Claude spawns a subagent via the Agent tool, your PreToolUse/PostToolUse hooks fire for every tool call the subagent makes as well.

Q&A

Official Resources

• Claude Code Hooks Reference — full list of events, matchers, and exit code behavior
• Claude Code Settings Documentation — where hooks fit into settings.json overall