Claude Code Hooks Explained: Complete Beginner's Guide

Here’s a number that should rethink how you configure your AI coding assistant: the average Claude Code bill sits at roughly $13 per developer per active day, and a significant chunk of that cost comes from instructions your model ignores about 20% of the time. That second part is the one you can actually do something about.

Claude Code hooks are the mechanism the community keeps circling back to when the conversation turns to making AI-assisted development deterministic rather than hopeful. They’re not a new feature — Anthropic has been expanding the system since early 2026 — but most developers still treat CLAUDE.md as the primary control surface and leave hooks entirely untouched. That’s starting to look like a costly habit.

Hooks vs. Prompts: The Reliability Gap

The core distinction is simpler than most guides make it. A line in your CLAUDE.md asking Claude to run a linter is a suggestion the model can forget. A hook that runs the linter after every edit is a guarantee, because Claude Code runs it, not the model. That architectural detail is the entire pitch.

Quantifying the gap: instructions in CLAUDE.md are advisory and followed approximately 80% of the time, while hooks provide deterministic enforcement that executes 100% of the time without requiring model cooperation, at near-zero context token cost. Every paragraph you write to plead with the model costs tokens on every turn. Hooks don’t consume context tokens at all — their configuration lives outside the main context window and they bypass compaction entirely.

The practical upshot is what I’d call a context-authority tradeoff. You’re exchanging high-cost, unreliable advisory control for low-cost, guaranteed deterministic enforcement. For any repeatable rule — formatting, linting, security gates, file protection — the math favors hooks overwhelmingly.

What Hooks Actually Are Technically

A hook is a command, HTTP call, or agent that the system triggers at defined lifecycle events, receiving a JSON payload on stdin, and can observe actions, inject context, or block operations. That’s the contract. No SDK, no plugin API, no daemon to register with. As Anthropic’s steering guide explains, hooks fire on lifecycle events, bypass compaction entirely, and carry low context cost because their configuration lives outside the main context window.

You configure hooks in a settings.json file under a hooks key, mapping event names to matchers and handler commands. The system fires your handler, pipes a JSON description of what’s happening into stdin — which tool, which session, working directory — and reads the result. For decision-point events, your exit code determines what happens next: exit 0 to allow, exit 2 to block.

As of mid-2026, Claude Code exposes roughly 30 lifecycle hook events, including PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit, SubagentStart, SubagentStop, Notification, PreCompact, Setup, SessionEnd, and PermissionRequest. That’s a substantially larger surface than the 12-15 events most older guides describe.

The Three Events You Need First

With thirty events available, the temptation is to over-engineer. Resist it. Three events cover the majority of production use cases.

PreToolUse fires before Claude calls any tool. This is your decision hook — inspect the proposed action and return an allow or deny verdict. Use it for security gating: blocking rm -rf, preventing .env access, stopping destructive git commands before they execute. A PreToolUse hook that exits with code 2 stops the tool cold.

PostToolUse fires after a tool call completes successfully. It can’t undo execution, but it can provide feedback and trigger follow-up actions. The canonical pattern is auto-formatting: every time Claude writes or edits a file under src/**, a PostToolUse hook runs your formatter. No approval clicks, no context switches.

Stop fires when Claude finishes its main response. This is your task-enforcement hook — exit 2 to force Claude to keep working if it’s trying to wrap up prematurely. Useful for ensuring tests pass before a session ends or verifying that a build succeeds before declaring done.

Path-Scoped Conditions Changed Everything

A critical fix landed in version 2.1.176 (June 12, 2026): path-scoped hook conditions like Edit(src/**), Read(~/.ssh/**), and Read(.env) now match correctly. Before this fix, documented syntax silently didn’t fire — a reliability gap that undermined the entire value proposition of deterministic enforcement.

This matters because it means you can now build hooks that run only when Claude touches specific paths. Format anything under src/** on edit. Block or warn on any attempt to read .env. These are per-path deterministic guards, not blanket “every tool call” hooks. A June 25 update (version 2.1.191) further fixed comma-separated hook matchers like "Bash,PowerShell" firing correctly.

Production Patterns Worth Wiring In

The community has converged on several high-value patterns that translate across codebases:

• PostToolUse for auto-formatting and linting — runs your formatter after every file edit, keeping diffs clean without manual intervention
• PreToolUse for blocking dangerous commands — intercepts rm -rf, .env access, and destructive operations before they execute
• Stop/Notification for alerts — triggers desktop notifications or Slack messages when long-running tasks complete
• PreToolUse for security gating — enforces access boundaries that the model can’t override

One caution from practitioners: if your formatter changes files, Claude receives a system reminder about those changes every time, which eats into your context window. The smarter approach is to format on commit via a Stop hook rather than after every individual edit.

The Instability Problem Nobody Mentions

Here’s where the honest tradeoff appears. The Backgrind practitioner guide explicitly notes that hook event names, payload fields, and decision semantics shift between releases, with the underlying JSON schema changing more than once. You need to treat documentation as a general shape rather than a stable spec.

This is the real cost of hooks: not setup time, but maintenance. Every Claude Code update is a potential breaking change to your hook configurations. If you’re wiring hooks into CI/CD pipelines or team-wide enforcement, you need a testing strategy for hook behavior alongside your normal test suite. The feature is production-ready, but “production-ready” and “stable interface” are different claims.

Where Hooks Fit in Your Control Architecture

The strongest configuration I’ve seen follows a clear hierarchy. Reserve CLAUDE.md exclusively for high-level, session-wide project context relevant to every interaction — directory structure, build commands, monorepo layout. Move every repeatable rule, enforcement pattern, and deterministic behavior into hooks. Skills handle procedural workflows like deploy checklists.

This combination minimizes context cost, maximizes behavioral reliability, and avoids the token waste and unreliability of advisory in-context instructions. If you’re using Claude Code across multiple tools, you might also want to look at how AGENTS.md, CLAUDE.md, and Cursor rules interact — the same principle of separating advisory context from deterministic enforcement applies across all three formats.

For teams running Claude Code at scale, the cost implications are real. If you’re evaluating the subscription tiers and their usage limits, factor in that effective hook configuration can reduce your context token consumption significantly — potentially keeping you on a lower plan than you’d otherwise need.

Start with one hook. A PostToolUse formatter or a PreToolUse .env blocker. Run it for a week. You’ll find the reliability difference is not subtle — and you’ll stop writing polite requests in CLAUDE.md for things that should be guarantees.