What are Claude Code hooks?
Claude Code hooks are shell commands that run automatically at set points in the agent’s lifecycle, such as before a tool runs or when a turn ends. Because they run every time instead of relying on the model, they are a dependable way to enforce rules and add checks.
Events
Hooks are defined in settings.json files and attached to an event. For tool events, a matcher lets you target specific tools, such as Bash or Edit.
- PreToolUse: before a tool runs; it can block the call.
- PostToolUse: after a tool finishes, for example to format the edited file.
- UserPromptSubmit: before your message reaches the model.
- Stop: when the agent finishes its turn.
- SessionStart: when a session begins, useful for adding context.
- Notification: when Claude Code sends a notification.
How it works
The hook command receives the event’s details, such as the tool name and input, as JSON on standard input. Its exit code tells Claude Code what to do: 0 means carry on, and 2 blocks the action and passes the error message to the model. For finer control, a hook can also return a decision and a reason as JSON.
What people use them for
Hooks turn anything the model might forget into a rule.
- Blocking dangerous commands or reads of files like .env.
- Running a formatter or linter after every edit.
- Rewriting commands so their output is shorter.
- Sending a notification or running tests when a turn ends.
Things to watch for
Hooks run with your user permissions and without asking, so don’t add someone else’s hook without reading it. A slow hook slows down every tool call, so keep them fast. Text a hook returns can end up in the model’s context, so keep it short.
Hooks in AgentVera
AgentVera runs several of its features as hooks in Claude Code agents. The Lean context profile, on the other hand, doesn’t load user-level hooks.
- Smart tools: four hooks that block repeat file reads, narrow full test runs to the affected tests, report new type errors right after an edit and share a command’s result between agents. All are on by default.
- RTK: Claude Code’s Bash commands are rewritten through a hook into versions with shorter output (git status → rtk git status).
- Codex has no hooks, so RTK works there through instructions, and smart tools run only in local Claude Code agents.
FAQ
Where are Claude Code hooks configured?
In settings.json files: ~/.claude/settings.json for your user, .claude/settings.json for the project and .claude/settings.local.json for your machine only. You can also manage them with the /hooks command.
How does a hook block a command?
If a PreToolUse hook exits with code 2, the tool call is blocked and the hook’s error output goes to the model as the reason.
Are hooks safe?
Hooks are shell commands that run with your permissions, so they’re as safe as what they contain. Read project hooks that come with a repo before you run them.
What’s the difference between a hook and a skill?
A hook is a command that runs every time a given event happens; the model doesn’t decide. A skill is a set of instructions and files the model loads when it judges it relevant.