What are Claude Code hooks, and how should you use them?

the short answer

A hook is a shell command Claude Code runs for you when a specific event fires. Common events include SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Notification, Stop, SubagentStart and SubagentStop, PreCompact and PostCompact, and SessionEnd, per the official hooks reference.

Use hooks for rules that must always happen rather than asking the model to remember. The guide frames this explicitly as deterministic control: format code after edits, validate commands, enforce project rules, and send notifications, instead of relying on the model to choose to do it.

how hooks differ from skills and subagents

Skills and subagents add capability and judgment. A skill packages reusable instructions a model can invoke, and a subagent is a spawned helper that does a subtask with its own context, both covered in existing RepoRadar answers.

Hooks add enforcement without judgment. A PreToolUse hook can block an edit to .env before it executes, and a PostToolUse hook can run a formatter after every Edit or Write. If the task needs a decision, use a skill or subagent. If the task needs an always-on rule, use a hook.

the events worth knowing first

Three events cover most practical setups. PreToolUse fires before a tool call and can block it, which makes it the right place for guards. PostToolUse fires after a successful tool call, which makes it the right place for formatting, linting, or logging. Notification fires when Claude Code needs input, which makes it the right place for desktop alerts.

Two more solve recurring annoyances. SessionStart with the compact matcher re-injects short project facts after context compaction, such as which package manager to use and which test command to run. Stop fires when Claude finishes responding and is the right place for a completion check. The reference lists the full lifecycle, including Setup, PermissionDenied, PostToolBatch, TaskCreated and TaskCompleted, worktree events, model-switch events, and MCP elicitation events, so check it before inventing a workaround.

three safe starter hooks

First, a notification hook so you notice when input is needed. The guide shows a Notification entry that calls osascript on macOS, notify-send on Linux, or a PowerShell message box on Windows. Test the underlying notifier on its own first, then register it and confirm it appears in /hooks.

Second, a formatter hook so edits stay consistent. The guide shows a PostToolUse entry with matcher Edit|Write that pipes the edited file path through jq into a formatter such as prettier. Scope the matcher narrowly at first, and confirm jq is installed.

Third, a protection hook so risky edits get stopped. The guide shows a PreToolUse entry for Edit and Write that calls a script checking the file path against patterns like .env, package-lock.json, and .git/, printing a block message to stderr and exiting 2 on a match. Start with a short pattern list you control, and test it by attempting a blocked edit on a scratch file.

where hook settings live

The reference defines five locations with different scopes. The user settings file applies to all projects on one machine. The project settings file applies to one project and can be committed to the repo. The project-local settings file applies to one project and stays gitignored. Managed policy settings are organization-wide and admin-controlled. Plugin hooks files ship with a plugin when it is enabled.

The practical split follows from that table. Keep personal notification hooks in user settings. Keep formatting, guard, and environment hooks that the whole team should share in project settings so they are reviewable in version control. Treat any project hooks file you did not write the way you would treat any new script dependency: read it before running it in a directory you care about.

safety rules before you commit a hook

Hooks run shell commands with your user permissions, so a careless hook can do more damage than a careless prompt. The reference includes workspace-trust guidance and a way to disable hooks, and it warns against unsafe variable handling and path traversal patterns.

Four rules keep the risk low. Keep each hook command short, quoted, and pinned to an explicit script path under the project directory. Never let a hook silently approve broad permissions or bypass modes for you; an auto-approve hook should match one narrow tool and one narrow condition. Keep secrets out of hook commands and out of logged output. Review project hooks in pull requests the same way you review code, because a committed hook runs for everyone who opens the project.

limits and debugging

Hooks are deliberately limited. Display-only events observe but do not decide, long commands can hit timeouts, and hook JSON output must match the documented schema or Claude Code ignores the decision part. Shell startup output is a common failure: an echo in a shell profile can corrupt the JSON the hook returns, so the guide recommends guarding profile output to interactive shells only.

When a hook misbehaves, work through a short checklist. Run /hooks to confirm the hook is registered. Pipe a sample event payload into the script by hand and check the exit code. Run with debug logging and watch for hook error lines. Prefer small scripts that read JSON from stdin with jq, exit 0 when no decision applies, and return only the documented fields when a decision does apply.

a useful next action

This week, add exactly two hooks. Add a Notification hook in your user settings so background sessions get your attention, and add one PreToolUse guard in one project that blocks edits to that project's most sensitive file pattern.

Verify both with /hooks, test the guard on a scratch copy, and only then consider a formatter or context-reinjection hook. Two working hooks teach more than six half-debugged ones.