Claude Code hooks can stop costly mistakes by letting you run automated checks before, during, and after Claude works, blocking dangerous actions before they happen. You define the rules—like forbidding edits to production files or requiring tests to pass—and Claude must follow them. This gives you a safety net that catches errors before they cost you time or money.
Formula
The calculator above works out your average pace and speed for a run or ride. The formulas are:
- Pace = Finish time ÷ Distance (minutes per kilometer)
- Speed = Distance ÷ (Finish time ÷ 60) (kilometers per hour)
Where:
- Finish time (t) is in minutes
- Distance (d) is in kilometers
Worked Example
Using the default values: finish time = 50 minutes, distance = 10 km.
- Pace = 50 ÷ 10 = 5.00 min/km
- Speed = 10 ÷ (50 ÷ 60) = 10 ÷ 0.8333 = 12.00 km/h
The calculator shows 5.00 min/km and 12.00 km/h, matching the example.
Why Hooks Matter
Claude Code is an AI coding assistant that can edit files, run commands, and interact with your system. Without safeguards, it might accidentally delete a database, overwrite a config file, or commit code that breaks the build. Hooks are user-defined scripts that run at specific points in Claude’s workflow, letting you intercept and review actions before they execute.
For example, you can create a hook that runs every time Claude tries to edit a file. The hook can check if the file is in a protected directory (like production/) and block the edit with a custom error message. This prevents costly mistakes before they happen.
How Hooks Work
Hooks are configured in a file called settings.json in your project’s .claude folder. Each hook has a matcher (which events trigger it) and a command (the script to run). The command receives JSON input with details about the event, and its output can control Claude’s behavior.
Common hook events include:
- PreToolUse – runs before Claude uses a tool (like editing a file or running a command)
- PostToolUse – runs after the tool finishes
- Notification – runs when Claude sends a notification
- Stop – runs when Claude finishes a response
- SubagentStop – runs when a subagent completes
For a PreToolUse hook, if the command exits with a non-zero code, Claude’s action is blocked. You can also include a JSON payload to display a custom error to the user.
Setting Up Your First Hook
Here’s a simple example that blocks edits to any file in a secrets/ directory:
- Create a folder
.claude/hooks/in your project. - Add a script
block-secrets.shwith the following content:
#!/bin/bash
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
if [[ "$file_path" == secrets/* ]]; then
echo '{"decision":"block","reason":"Editing secrets is not allowed."}' >&2
exit 1
fi
exit 0
- Make it executable:
chmod +x .claude/hooks/block-secrets.sh - In
.claude/settings.json, add:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"command": ".claude/hooks/block-secrets.sh"
}
]
}
}
Now, whenever Claude tries to edit a file in secrets/, the hook blocks it and shows your reason. You can extend this pattern to check for other conditions—like running tests before allowing a commit, or scanning for hardcoded API keys.
Common Mistakes and Pitfalls
Hooks are powerful but can be tricky. Here are common issues:
- Incorrect JSON parsing – the input is JSON, so use a tool like
jqto extract fields. A simple grep might fail on multi-line values. - Not handling all events – if your matcher is too broad, the hook runs on every edit, slowing things down. Be specific.
- Silent failures – if the script exits 0 without checking anything, it lets everything through. Always test with a known case.
- Path issues – use absolute paths or relative to the project root, not the current working directory, which may change.
- Missing dependencies – if your script uses
jqor other tools, ensure they are installed on the user’s system.
Best Practices for Effective Hooks
To get the most out of hooks:
- Start small – add one hook, test it, then expand.
- Log everything – write to a log file for debugging.
- Use clear error messages – tell the user exactly what was blocked and why.
- Combine with other tools – hooks can call linters, formatters, or test runners.
- Keep them fast – a hook that takes 10 seconds will frustrate users.
Frequently Asked Questions
Can hooks completely prevent costly mistakes?
No, hooks are a strong safeguard but not a guarantee. They only run at defined points and depend on the quality of your scripts. A hook that only checks file paths won’t catch a logic error in the code Claude writes. Always review changes, especially in critical systems.
Do hooks work with all Claude Code versions?
Hooks were introduced in a specific version and have evolved. Check the official documentation for your version. Most features are stable, but new events may be added. Keep your Claude Code updated to use the latest hook capabilities.
Can I use hooks to run tests automatically?
Yes, a common use is to run a test suite before allowing a commit. Create a PreToolUse hook for the Commit tool that runs your tests and blocks the commit if they fail. This ensures Claude never commits broken code.
What if a hook itself has a bug?
If a hook script fails (e.g., missing file, syntax error), Claude Code will typically skip the hook and continue, but you’ll see an error in the output. To avoid this, test your hooks thoroughly and make them resilient to missing inputs.
Can hooks be shared across a team?
Yes, hooks are stored in the project’s .claude folder, which can be committed to version control. Team members will automatically use the same hooks when they pull the repo. This ensures consistent safety rules.
Do hooks work with subagents?
Yes, there is a SubagentStop event that fires when a subagent finishes. You can use it to validate the subagent’s output or log its actions. This is useful for monitoring complex multi-step tasks.
Related
Formula used
in t | Finish time | min | 50 | 0 in d | Distance | km | 10 | 0 | 100000 out pace | Average pace | min/km | t / d | 2 out speed | Average speed | km/h | d / (t / 60) | 2
Each line is one input (in, sel, list) or one result (out: label, unit, formula, decimals). How the calculators work
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Samsung Smart Speaker Rollable Display: Facts
- HP 9730e: Wide Prints, Not A3 Scans
- What 8888 Does When You Use It as DNS Server
- Credential Manager: Seamless Sign-In Explained
- API Governance for Public Data: What Growing Portfolios Need
- Enterprise AI Hidden Cost: Data Architecture ROI