Claude Code hooks are commands that Claude Code runs every time an event fires, such as before a tool call or when a session ends, set under hooks in settings.json. Exit code 2 or a JSON deny blocks the action; any other failure lets it go ahead unless the hook sets onFailure to block.
Free for 3 seats · No credit card · One command signs in every agent on your machine
Sample data
Stack in the Zest app: how well your setup is wired, and what raises the score
USED BY ENGINEERING TEAMS AT
What are Claude Code hooks?
A hook is a handler that runs every time its event fires: before a tool call, after a file edit, when you submit a prompt, when the session ends. A CLAUDE.md instruction is advice Claude may follow; a hook always runs. Claude Code best practices for teams covers which rules belong in a hook.
Most hooks are shell commands: Claude Code sends the event as JSON on stdin, and the command answers with an exit code and, optionally, JSON on stdout. Other handler types post the event to a URL (http), call an MCP tool, or ask a model or a subagent.
This .claude/settings.json blocks edits to protected files before they happen and runs Prettier on every file Claude writes. Both commands read the event with jq, so it has to be on your PATH:
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
for pattern in ".env" "package-lock.json" ".git/"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done
exit 0
How do I use hooks in Claude Code?
Pick the event you care about, write a command that reads the event's JSON on stdin, and list both under the hooks key in a settings file. Use .claude/settings.json to share the hook with your team or ~/.claude/settings.json to keep it for yourself, then run /hooks to confirm it loaded.
Pick an event and, on tool events, a matcher such as Edit|Write. The events table below lists the common ones.
Run the command in your own shell with a sample event on stdin before you commit it.
Exit 2 with a reason on stderr to block the action, on events that allow it, or exit 0 to let it go ahead.
Where hooks are configured
Hooks sit under the hooks key of a settings file, never in a file of their own: only plugins use a separate hooks/hooks.json. Hooks from every location run, so a project hook adds to yours instead of replacing it. The /hooksslash command lists every active hook and where it came from.
Command hooks run with your full user permissions. Settings-file hooks wait for the folder's trust dialog, but claude -p skips it, so read a repository's .claude/settings.json before you script Claude over code you didn't write.
The hooks reference lists more than 30 events. A matcher picks which occurrences fire a group: the tool name for tool events, the source or reason for session events. Matchers are case-sensitive. One made only of letters, digits, _, -, | and , lists exact names, such as Edit|Write; any other character makes it an unanchored regex, so Edit.* also matches NotebookEdit. MCP tools are named mcp__server__tool, so mcp__github__.* covers one server.
On tool events, a handler's if field filters further with permission-rule syntax, such as Bash(git *) or Edit(*.ts), so the command doesn't even start for other calls.
The events most hooks use, from Anthropic's hooks reference. The last column is what exit code 2 does.
Event
Fires
Matcher
Exit 2
SessionStart
A session starts or resumes
startup, resume, clear, compact, fork
Can't block
UserPromptSubmit
You send a prompt
None
Rejects the prompt
PreToolUse
Before a tool call
Tool name
Blocks the call
PermissionRequest
Before a permission prompt
Tool name
Ignored: deny with JSON
PostToolUse
After a tool call succeeds
Tool name
Can't undo; stderr goes to Claude
Stop
Claude finishes responding
None
Claude keeps working
Notification
Claude Code sends a notification
Notification type
Ignored
SessionEnd
The session ends
clear, resume, logout and more
Can't block
How a hook allows or blocks
A hook answers with its exit code (the table below) or, for finer control, exits 0 and prints JSON. A PreToolUse hook sets permissionDecision to allow, deny, ask or defer; when hooks disagree, deny wins over defer, ask and allow, and updatedInput replaces the tool's whole input. A deny holds even in bypassPermissions mode, but an allow can't override a deny rule in settings. This output denies the call:
stdout of a PreToolUse hook
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database writes are not allowed"
}
}
Command hook exit codes, from Anthropic's hooks reference.
Exit code
What happens
0
Success. Stdout that starts with { is read as JSON; for UserPromptSubmit and SessionStart, plain text is added to Claude's context
2
Blocks, on the events that can block. Stderr, or the JSON reason, tells Claude why, and a JSON allow can't override it
Any other, including 1
A non-blocking error: the action goes ahead and the transcript shows stderr's first line, unless the hook sets onFailure to block
How long can a Claude Code hook run, and do hooks run in parallel?
A command, HTTP or MCP tool hook can run for 600 seconds by default, a prompt hook for 30 and an agent hook for 60, and each accepts its own timeout. Every hook that matches an event runs in parallel, so one hook can't rely on another's result.
These limits come from Anthropic's hooks reference, which we read on November 10, 2026.
Limit
Value
Events
33
Handler types
command, http, mcp_tool, prompt and agent (experimental)
Default timeout
600 seconds for command, http and mcp_tool; 30 for prompt; 60 for agent
Shorter defaults
30 seconds on UserPromptSubmit, PreModelSwitch and PostModelSwitch, and 10 on MessageDisplay, for command, http and mcp_tool
SessionEnd
All its hooks share 1.5 seconds; a longer per-hook timeout raises that, up to 60
Running at once
All matching hooks, with at most 12 prompt or agent hooks
Output to Claude
10,000 characters; anything longer is saved to a file and Claude gets a preview of up to 2,000
Block on failure
onFailure set to block on a command or http hook, from v2.1.295; no effect on Stop, SubagentStop, TaskCompleted, TeammateIdle or background hooks
When should you use a hook instead of CLAUDE.md or a skill?
Use a hook when something has to happen every time, such as blocking edits to .env or running a formatter after each write, because it runs whatever Claude decides. Use CLAUDE.md for guidance Claude should weigh, and a skill for a procedure it picks up when the request fits.
A command hook suits a check a script can answer with a yes or a no. If the check needs judgment, Anthropic's prompt and agent hooks ask a model instead. Keep anything you wouldn't run with your full user permissions out of hooks, and test each one before you rely on it, since a broken hook lets the action through unless it sets onFailure.
Claude Code hooks examples
Anthropic's hooks guide has a ready-made config for each of these. The first two are the example at the top of this page.
Common hooks and their events, from Anthropic's hooks guide, read November 8, 2026.
What you want
Event
Matcher
Block edits to protected files
PreToolUse
Edit|Write
Run a formatter after every edit
PostToolUse
Edit|Write
A desktop notification when Claude needs input
Notification
Empty: all types
Re-inject context after compaction
SessionStart
compact
Auto-approve one permission prompt
PermissionRequest
ExitPlanMode
When a hook fails quietly
Only exit code 2 blocks, so a broken hook stops nothing unless it sets onFailure to block. One of our repositories runs its formatter in a PostToolUse hook after every Edit and Write; on a laptop without pnpm it failed 124 times in two days (exit code 127, command not found), and Claude carried on each time, so the formatter never ran. Exit code 127 is the shell's own code for a command it can't find, so a hook that reports it, in Claude Code or Codex, has a wrong path or a binary missing from PATH.
Run a hook's command in your own shell before you commit it, with a sample event on stdin. In a session, /hooks shows whether it loaded, and claude --debug writes each match, exit code and output to ~/.claude/debug/<session-id>.txt.
Common hook problems, from Anthropic's hooks guide and configuration-debugging docs.
Symptom
Usual cause
Never fires
A lowercase or array matcher, hooks in a file of their own, or hooks in ~/.claude.json instead of ~/.claude/settings.json
"hook error" in the transcript
The script isn't executable (chmod +x), the path is wrong, or jq is missing
JSON decision ignored
Your shell profile prints text before the JSON, or permissionDecision sits outside hookSpecificOutput
A Stop hook loops
Exit 0 when the input's stop_hook_active is true; Claude Code overrides a Stop hook after eight blocks in a row
Do Claude Code hooks work the same way in Cursor and Codex?
Close, but not the same. All three run a command when an event fires, pass it the event as JSON on stdin and block on exit code 2. Codex's events share Claude Code's names, in its own config files; Cursor has its own event names but also runs the hooks in Claude Code's settings files by default.
From each vendor's hook docs, read November 8, 2026.
What
Claude Code
Codex
Cursor
Config
The hooks key in a settings file
hooks.json or [hooks] in config.toml
.cursor/hooks.json
Any other failure
The action goes ahead unless onFailure is block
Not spelled out in its hooks docs
The action goes ahead unless failClosed is on
Runs hooks from .claude/settings.json
Yes
Not listed
Yes, on by default
Does Codex have hooks?
Yes, on by default. Codex reads them from a hooks.json or [hooks] tables in config.toml, in ~/.codex or the repository's .codex folder, and a Codex plugin can ship its own. The events mirror Claude Code's: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, the subagent and compaction events, and a few more. A hook you add yourself runs only after you review and trust it in /hooks.
Blocking works the same way: exit code 2 with a reason on stderr, or JSON with permissionDecision set to deny. An ask decision is parsed but not supported yet. Zest's Codex plugin uses two hooks, SessionStart and UserPromptSubmit, to keep its login fresh. Every Codex event, what a hook gets on stdin and the fixes for exit code 127 are on Codex hooks.
Does Cursor have hooks?
Yes. Cursor reads .cursor/hooks.json in the project and ~/.cursor/hooks.json, plus enterprise and team hooks that take precedence. Its events have their own names: beforeShellExecution, beforeMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, stop, and generic preToolUse and postToolUse.
Exit code 2 blocks here too, and other failures let the action go ahead unless the hook sets failClosed. Cursor also runs the hooks in Claude Code's settings files, mapping their events to its own, while its setting for third-party configs is on, which it is by default. A hook written for Claude Code can then fire in both tools, so test it in each. Cursor doesn't support Notification or PermissionRequest from those files, and it maps the Bash tool to Shell and Edit to Write.
Hook examples from a real plugin: Zest
Zest builds AI coding analytics from three hooks: each session's models, tokens, skills, subagents and MCP tools, next to the branch, commits and pull request it touched, shown as Claude Code usage per engineer.
If you want these events measured for every engineer without writing the hooks yourself, that is what the plugin does. If you need one formatter or one guard on .env, the config at the top of this page is all you need.
This is the plugin's hooks/hooks.json. PostToolUse has no matcher, so it runs after every tool call. Each hook has a timeout, exits 0 and returns no decision: Zest records, and never blocks or changes what Claude does.
Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month. See pricing
Hooks are commands a coding agent runs at fixed points in its work, such as before a tool call or when a session ends. Claude Code, Codex and Cursor all have them, and in each the agent passes the event as JSON on stdin and exit code 2 can block the action.
What is the difference between hooks and skills?+
A skill is instructions Claude chooses to use when a request matches it. A hook is code Claude Code runs every time its event fires, whatever Claude decides, so use a hook for anything that must always happen.
Why isn't my Claude Code hook running?+
Run /hooks: a hook that isn't listed didn't load, usually because it sits outside a settings file's hooks key or its matcher is an array. If it is listed, check that the matcher spells the tool name exactly (Bash, not bash), then start claude --debug and read the log.
Do hooks run inside subagents?+
Yes. Hooks from settings files, managed settings and plugins fire for a subagent's tool calls too, and the input carries agent_id and agent_type so a script can tell them apart.
Can I turn all hooks off?+
Yes. Set disableAllHooks to true in your settings, or pass --settings '{"disableAllHooks": true}' for one run; hooks from managed settings keep running. Administrators can go the other way with allowManagedHooksOnly, which blocks user, project, local and plugin hooks.