Claude Code hooks are shell commands that Claude Code runs automatically at defined points during a session. Instead of manually running formatters, tests, or notifications, you can wire them to fire on every file edit, every tool call, or every time the agent turn ends. This guide covers the hook types, the configuration format, and practical examples you can copy today.
Claude Code hooks: the four event types
There are four hook events you can attach commands to:
- PreToolUse — fires before any tool executes (file edit, bash command, web fetch, and so on)
- PostToolUse — fires after a tool finishes, with access to the tool result
- Notification — fires when Claude sends a notification to the user
- Stop — fires when the agent finishes its turn
How to set up hooks in Claude Code
Hooks live in ~/.claude/settings.json. Each entry has a matcher (a regex matching tool names) and a command (a shell string to run). Here is the basic structure:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "prettier --write $CLAUDE_TOOL_INPUT_FILE_PATH" }
]
}
]
}
}The environment variable $CLAUDE_TOOL_INPUT_FILE_PATH holds the path of the file that was just written. Leave matcher empty to match every tool.
Practical examples for Claude Code hooks
Three examples worth adding to your workflow right now:
Auto-format on every edit: A PostToolUse hook matching Edit|Write can call prettier, black, or gofmt on the changed file. This keeps code style consistent even when Claude edits multiple files in a single turn.
Run tests after writes: Matching Write and running npm test -- --testPathPattern=$CLAUDE_TOOL_INPUT_FILE_PATH immediately confirms that each new file passes its test suite before the session ends.
Desktop notification on task end: A Stop hook calling osascript -e 'display notification "Claude finished" with title "Claude Code"' on macOS alerts you the moment a long autonomous run completes — no more checking back every few minutes.
Security considerations
Hooks run as the same user as Claude Code, with full shell access. Treat hook commands like any other shell script: avoid embedding secrets in the command string, use environment variables or a secret manager for sensitive values, and review hook output in the session log before trusting external scripts.
Where to go next
If Claude Code is not yet installed on your machine, the Claude Code Mac setup guide covers everything from installation to first use. For the complete list of environment variables, exit-code behaviour, and advanced hook patterns, see the official hooks documentation for Claude Code on the Anthropic developer site.