Claude Hooks: What They Are
and Why They Change Everything

What hooks are

When Claude Code operates on your project, it uses tools: it reads files, writes files, runs shell commands, makes commits. What most people don't know is that you can attach code to those moments. That code is called a hook.

A hook is a script — usually a shell script — that runs automatically before or after a specific Claude tool call. You define it in your .claude/settings.json. Claude Code reads the settings and runs your hook as part of its normal operation. Claude doesn't have to be told about it. It just happens.

The two main hook types are PreToolUse (runs before Claude calls a tool) and PostToolUse (runs after). If a PreToolUse hook exits with a non-zero code, Claude sees the failure and stops the tool call. That's the mechanism that makes hooks genuinely powerful — they're not just logging. They can veto.

Why this matters

Think about what Claude does without hooks: it writes code, runs tests, makes commits. It does this based on your instructions and its own judgment. That's mostly fine. But there are cases where you want a guarantee — something that holds no matter what Claude decides.

You want tests to pass before a commit. You want your session memory file loaded at the start of every session. You want a Slack ping when a long build finishes. You want a log entry for every file Claude touches on a particular project. None of these require Claude to agree. Hooks run at the harness level — below Claude's awareness. That's the point.

Example 1: a pre-commit hook that runs tests

Here's the simplest version of a hook I actually use. It runs the test suite before Claude makes a git commit, and blocks the commit if tests fail.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/pre-commit-check.sh"
          }
        ]
      }
    ]
  }
}
      

#!/bin/bash
# Only intercept git commit calls
if echo "$CLAUDE_TOOL_INPUT" | grep -q '"git commit"'; then
  echo "Running tests before commit..."
  npm test
  exit $?
fi
exit 0
      

When Claude tries to run git commit, this script runs first. If npm test exits non-zero, the commit doesn't happen. Claude sees the failure output and handles it — usually by investigating what broke. You didn't have to tell Claude "run tests before committing." The hook enforces it structurally.

Example 2: a session-start hook that loads your memory file

This is the hook I reach for most. When Claude Code starts a session, a PostToolUse hook can fire immediately and inject your SESSION.md content — so you never have to paste it manually.

The mechanism: use a PostToolUse hook on the first Bash call in a session (or attach it to session initialization). The hook reads your SESSION.md and writes its contents to stdout. Claude Code surfaces that output in the session context.

Combined with the SESSION.md approach from the session memory post, this means every session starts pre-loaded. No pasting, no re-explaining.

What you see when a hook fires

If tests had failed, Claude would see the test output in the hook result and report the failures before retrying.

What you can build with hooks

• Enforce code quality gates — run a linter or formatter before every file write; Claude can't skip it
• Automatic session memory loading — inject your SESSION.md at the start of every session without pasting
• Audit logging — write every file Claude touches to a log file, timestamped, for project records
• Notification hooks — send a desktop notification or Slack message when a long-running build finishes
• Environment validation — before any Bash execution, check that required env vars or services are present and fail loudly if not

Book 2 in the series goes deep on automations and hooks — building full hook systems, chaining hooks across tool types, and using hooks to implement approval workflows where Claude must confirm before taking destructive actions. It's in progress.

Read Book 2: Automations →