If you’ve spent any time working with AI coding agents like Claude Code, you’ve probably felt both the magic and the frustration. One minute, it’s writing flawless boilerplate code; the next, it’s completely ignoring the carefully crafted instructions in your CLAUDE.md file. It’s a common story you see popping up on Reddit and Hacker News, you get inconsistent results, or what some people have started calling "LLM slop."
That feeling of losing control during a long session is exactly why Claude Code hooks exist. They’re your way of bringing predictable, solid control back to your AI assistant. Instead of politely suggesting a workflow, you get to enforce it. This guide is your practical hooks reference for Claude Code, breaking down what they are, why they matter, and how you can use them to make your AI-powered development a whole lot more reliable.
What are Claude Code hooks?
Simply put, hooks are shell commands that you define to run automatically at certain points in the Claude Code workflow. If you’ve ever used Git hooks like pre-commit or post-commit to keep your repository clean, the concept will feel immediately familiar. Just like Git hooks can force every commit to be linted and tested, Claude Code hooks make sure your AI agent follows your rules, every single time.
An illustration of Claude Code hooks, showing how they intercept and automate different stages of the AI workflow. This image provides a great hooks reference for Claude Code users.::The real difference between a hook and a prompt comes down to one thing: guaranteed execution. An instruction in your CLAUDE.md file is a suggestion. The AI will probably follow it, but in a long conversation, it might get pushed out of the context window or just de-prioritized. A hook, on the other hand, is a hard-coded rule. It’s a command that is guaranteed to run when its specific event happens. No ifs, ands, or buts.
You can set them up in two places, which gives you some nice flexibility:
-
~/.claude/settings.json: This is for your personal, user-level hooks. Anything you put here will apply to all of your projects. Think of it as your global configuration. -
.claude/settings.json: This is for project-specific hooks. You can check this file into version control, so everyone on your team gets the same automated rules. It’s perfect for enforcing team-wide standards.
A screenshot showing the settings.json file where users can configure their hooks, a key part of this hooks reference for Claude Code.::This setup takes your AI assistant from a brilliant but sometimes flaky partner to a reliable, automated tool you can count on.
From unreliable prompts to solid control with hooks
Relying only on prompts and CLAUDE.md files can feel like a roll of the dice. Large language models have a limited attention span (their context window), and as your session goes on, those initial instructions can get lost in the noise. The feedback from developers is pretty clear on this one; instructions can be "hit or miss," which often leads to you having to go back and clean things up manually. Hooks are the answer to turning those suggestions into actions that always happen.
So what does this actually look like in your day-to-day workflow?
-
Enforce code quality on autopilot. You can automatically run linters like
ruffor formatters likeprettierafter Claude modifies a file. You’ll never have to remind the AI to format its code again, and you won’t have to fix style issues yourself. -
Automate the boring stuff. Ever wanted a desktop notification when a long task finally finishes? Or how about automatically creating a git commit with the user’s prompt as the message after each successful run? You can even log every shell command for auditing. All of this is possible with hooks.
-
Improve safety and prevent mistakes. You can set up hooks to block Claude from running potentially destructive commands like
rm -rf. You could also prevent it from touching sensitive files like your.envorpackage-lock.json, giving you peace of mind.
A practical reference for Claude Code hooks
Alright, let’s get into the details. This section is your go-to reference for getting started with the most common and useful hooks. Think of it as a cheat sheet for putting your AI agent on rails.
Key hook events
Hooks are all about timing. They’re tied to specific events that happen while the agent is working. While the official documentation has the full list, these are the four you’ll probably find yourself using over and over.
| Hook Event | When It Runs | A Common Use Case |
|---|---|---|
UserPromptSubmit | Before Claude even sees your prompt. | You can inject extra context here, like the current date or your git branch, or even block prompts you don’t want the AI to handle. |
PreToolUse | Right before Claude executes a tool (like Bash or Write). | This is your chance to block unsafe commands, ask for user approval, or set up a temporary environment for the tool to run in. |
PostToolUse | Right after a tool finishes successfully. | Perfect for running formatters or linters on newly created code, logging the action, or checking the tool’s output. |
Stop / SubagentStop | When the main agent or a subagent wraps up its task. | A great spot to send a notification, run a cleanup script, or automatically commit the work that was just done. |
Example 1: Keeping code clean with a PostToolUse hook
Let’s start with a classic. Auto-formatting code is a simple win that saves a ton of time and keeps your codebase looking professional.
The goal: Automatically run prettier on any TypeScript file that Claude writes or edits.
To get this working, you’ll add a hook to your settings.json file. We’ll use a matcher to make sure this hook only fires for the Write, Edit, and MultiEdit tools, since those are the ones that modify files.
"`json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r ‘.tool_input.file_path’ | { read file_path; if echo \"$file_path\" | grep -qE ‘\\.(ts|tsx)$’; then npx prettier ---write \"$file_path\"; fi; }"
}
]
}
]
}
}
"`
That shell command might look a little intimidating, but here’s a quick breakdown of what it’s doing:
-
jq -r ‘.tool_input.file_path’: The hook receives a bunch of JSON data about the event via standard input (stdin). This command usesjqto pull out the path of the file that was just changed. -
| { read file_path; … }: It then "pipes" that file path into a small script block so we can work with it. -
if echo \"$file_path\" | grep -qE ‘\\.(ts|tsx)$’: This is a simple check to see if the file path ends with.tsor.tsx. -
then npx prettier ---write \"$file_path\"; fi;: If it’s a TypeScript file, it runsprettierto format it right then and there.
Once this hook is active, any TypeScript code Claude touches will be perfectly formatted, guaranteed.
Example 2: Getting custom notifications with a Stop hook
Have you ever kicked off a longer task with Claude, switched over to another window, and then completely forgotten about it? A simple desktop notification can make your workflow feel so much smoother.
The goal: Get a desktop notification on macOS when Claude finishes its current task.
This one is much simpler. We just need to configure a hook for the Stop event.
"`json
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e ‘display notification \"Claude has finished!\" with title \"Claude Done\" sound name \"Glass\"‘"
}
]
}
]
}
}
"`
This command uses osascript, a handy tool built into macOS, to pop up a system notification. Now you can fire off a complex task, go grab a coffee, and get a friendly ping the moment your AI assistant is ready for whatever’s next.
This video provides a deep dive into how you can use the five key hooks for more advanced control and observability over Claude Code.
What about automating work beyond the command line?
The power of hooks is amazing for developers. We’re comfortable writing scripts, digging through JSON, and living in the shell. But what if you’re a support manager, not a developer? You still need to automate workflows with the same level of reliability, but you need it without the code.
This is where a tool like eesel AI comes into the picture. It offers the same kind of reliable, deterministic control you get with hooks, but through a no-code, visual interface that’s built for business teams. It connects to your existing help desk (like Zendesk or Intercom) and knowledge sources, letting you automate support without needing to write a single line of code.
The parallels between the two approaches are pretty clear:
-
A developer writes a
PreToolUsehook to block dangerous commands. A support lead uses eesel AI’s workflow builder to create a rule that automatically escalates any ticket from a VIP customer that contains the word "urgent." -
A developer sets up a
PostToolUsehook to run a linter on new code. A support team uses eesel AI’s AI Triage to instantly tag, route, and categorize new tickets based on their content, all set up with a few dropdown menus. -
A developer might write a custom script to test their hooks. With eesel AI, you get a powerful simulation mode right out of the box. You can safely test your AI agent on thousands of your team’s past tickets to see exactly how it will behave before it ever talks to a real customer.
With a platform like eesel AI, business teams get that same granular control and reliable automation, but they can get it up and running in minutes, not months. You get full control over the AI’s behavior through a simple UI, and you can test everything completely risk-free.
Reliable AI automation for any team
This hooks reference for Claude Code is about more than just a new feature; it’s about a bigger shift toward building AI systems that are more robust and reliable. For developers, hooks are a fantastic tool for adding predictable automation to coding workflows, letting us move past the sometimes-unreliable nature of prompts.
But the underlying principle is universal. Whether you’re a developer scripting a coding agent or a support leader setting up a service bot, the end goal is the same: creating reliable, customizable AI automation that you can actually trust to do the job right.
If you’re a developer, I encourage you to start playing around with hooks today. They can seriously improve your workflow. And if you’re looking to bring that same level of reliable AI automation to your customer support team, set up your first AI agent with eesel AI in minutes.
Frequently asked questions
Hooks are shell commands you define to run automatically at specific points within the Claude Code workflow. They are designed to enforce rules and actions, providing predictable and reliable control over your AI agent’s behavior.
Unlike prompts, which are merely suggestions the AI might prioritize differently over time, hooks guarantee execution. They provide a robust way to ensure critical steps and quality checks are consistently applied, regardless of the conversation’s length or context.
Hooks can be configured in two main locations: ~/.claude/settings.json for personal, user-level settings that apply globally, or .claude/settings.json for project-specific settings that can be version-controlled and shared with a team.
Yes, you can set up a PreToolUse hook to intercept and block potentially destructive commands, such as rm -rf, before Claude executes them. This is a crucial feature for enhancing safety and preventing unintended errors.
Key hook events include UserPromptSubmit (before a prompt is processed), PreToolUse (before a tool is executed), PostToolUse (after successful tool execution), and Stop/SubagentStop (when a task concludes). These events allow for automation at critical stages.
While this hooks reference Claude Code offers granular, code-based control primarily for developers, platforms like eesel AI provide similar reliable and deterministic AI automation through a no-code, visual interface. This makes advanced AI workflow control accessible to business teams without programming expertise.
