Introducing Hooks

What Are Hooks?

Hooks are custom commands that execute automatically before or after Claude Code uses a tool. They create automated feedback loops -- intercepting tool calls to enforce rules, run checks, or provide additional context. Think of them as middleware for Claude's tool use pipeline.

Hooks intercept the tool use pipeline before and after execution

ℹ️

Two Types of Hooks

Pre-tool use hooks run BEFORE the tool executes and can block the operation (exit code 2). Post-tool use hooks run AFTER the tool executes and provide feedback but cannot block. Both receive the tool call details as JSON via stdin.

Hook Configuration

Hooks are configured in your Claude settings file. Each hook specifies a matcher (which tools to intercept) and a command to execute. The hook receives tool call data as JSON via stdin and communicates back through exit codes and stderr.

jsonHook configuration in settings file

// .claude/settings.local.json
{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "read|grep",
        "command": "node ./hooks/read_hook.js"
      }
    ],
    "postToolUse": [
      {
        "matcher": "edit|write",
        "command": "node ./hooks/type_check.js"
      }
    ]
  }
}

Aspect	Pre-Tool Use Hook	Post-Tool Use Hook
When it runs	Before tool execution	After tool execution
Can block?	Yes (exit code 2)	No
Primary use	Guard against dangerous operations	Quality checks, feedback loops
Examples	Block .env file access, validate file paths	Run type checker, check for duplicates
Exit code 0	Allow the tool call	Success (feedback optional)
Exit code 2	Block the tool call + send error	N/A (cannot block)

Pre vs Post hook capabilities

✨

Matcher Syntax

The matcher field uses pipe-separated tool names: 'read|grep' matches both the read and grep tools. Ask Claude directly for the list of available tool names if you are unsure which to target.

Common Hook Use Cases

Hooks unlock powerful automated workflows. Here are the most common patterns used by Claude Code teams:

•Security: Block access to sensitive files (.env, credentials, private keys) with pre-hooks
•Type safety: Run tsc --no-emit after every TypeScript file edit to catch type errors immediately
•Code quality: Launch a separate Claude instance to check for duplicate code in critical directories
•Formatting: Auto-format files after creation using prettier or eslint --fix
•Testing: Run related tests after code edits to catch regressions immediately
•Linting: Run linters on modified files and feed violations back to Claude for self-correction

⭐

The Feedback Loop

The most powerful pattern is the post-hook feedback loop: Claude edits code -> hook runs a check -> if issues found, stderr feedback goes back to Claude -> Claude fixes the issues automatically. This creates a self-correcting development cycle.

Key Takeaways

✓Hooks are custom commands that execute before (pre) or after (post) Claude uses a tool
✓Pre-hooks can block operations (exit code 2) -- ideal for security rules like blocking .env access
✓Post-hooks provide feedback but cannot block -- ideal for type checking and quality enforcement
✓Hook configuration uses matcher (tool names) + command in .claude/settings.local.json
✓The most powerful pattern is automated feedback loops: edit -> check -> fix -> repeat

Check Your Understanding

Test what you learned in this lesson.

Q1.What is the key difference between pre-tool use hooks and post-tool use hooks?

Q2.A post-tool use hook that runs 'tsc --noEmit' finds type errors after Claude edits a file. What happens next?

Q3.Which exit code should a pre-hook use to block a tool call?

Q4.What is the matcher field used for in hook configuration?

GitHub Integration

Defining Hooks