Automate Claude Code Safely with Hooks

Quick answer

Hooks run a script, HTTP request, prompt, or subagent when a Claude Code lifecycle event matches. Use them for deterministic guarantees—formatting after edits, blocking forbidden operations, recording audit data, or notifying on completion. Hook commands execute with your credentials, so review and test them like production code. Consult the hooks reference for current events and schemas.

Choose the smallest reliable event

Common patterns include:

• Before a tool call: deny dangerous paths or require an additional check.
• After an edit: format only the changed file or run a focused validator.
• On stop/notification: send a local notification or capture a summary.
• At session start: load dynamic environment context.

Do not run the full test suite after every edit. It creates latency, noise, and feedback loops. Format locally after edits; run focused tests after logical units; reserve full verification for completion.

Example design: protect generated files

Goal: prevent direct edits under src/generated/.

1. Match file-edit tool events.
2. Parse the structured input; do not regex an untrusted shell string.
3. Normalize the path.
4. If it resolves under src/generated/, return the documented blocking status and a message to run the generator.
5. Allow all other files.

Test allowed paths, denied paths, ../ traversal, symlinks, spaces, and malformed input.

Example design: focused post-edit checks

For TypeScript edits:

Edit occurs → formatter runs on changed path → fast type/lint check runs for
affected package → concise result returns to Claude.

The script should quote paths, use timeouts, cap output, and propagate failure. A hook that always exits successfully while printing an error is not enforcement.

Avoid loops and hidden mutation

A post-edit hook that edits another file may trigger another hook. Define idempotence and a termination condition. Prefer check-only behavior unless mutation is necessary and obvious.

Never use a hook to silently commit, push, deploy, install packages, or transmit source. Those are meaningful external changes and require explicit authorization.

Hook review checklist

• Is the event narrow enough?
• Is input parsed as structured data?
• Are paths normalized and quoted?
• Is there a timeout?
• Is output bounded and actionable?
• Does failure actually block when intended?
• Can the hook recursively trigger itself?
• Does it read secrets or make network calls?
• Can a teammate understand and disable it?

FAQ

When is a hook better than CLAUDE.md?

Use a hook when compliance must be deterministic. CLAUDE.md guides model behavior; it is not an enforcement boundary.

Can hooks call an LLM?

Claude Code supports several hook handler types, including prompt- and agent-based handlers. Use deterministic command hooks for hard security policy and model-based hooks for judgment with appropriate safeguards.

Why did a hook not run?

Check the event name, matcher, settings scope, hook logs, executable permissions, interpreter path, timeout, and whether another policy disabled it.