What are Claude Code hooks?
Claude Code hooks are commands, HTTP calls, MCP tools, prompts or subagents that Claude Code runs on its own at set points in a session: before a tool runs, after it finishes, when you submit a prompt, when the agent stops. A hook receives the event as JSON and can observe it, add context, or block it.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
You add a hook in a settings file, a plugin's hooks.json, or a skill's frontmatter: an event name, an optional matcher, and a handler.
When the event fires and the matcher matches, Claude Code sends the event as JSON: session id, cwd, and for tool events the tool name and input.
Your handler runs. A command hook reads stdin, an HTTP hook receives a POST, and a prompt or agent hook asks a model to decide.
Exit 0 means carry on, and any JSON on stdout is applied: a permission decision, extra context, or a rewritten input.
Exit 2 blocks the action, with stderr as the reason. Any other code is a non-blocking error: the action goes ahead and the transcript shows a notice.
Hooks versus instructions in CLAUDE.md
A line in CLAUDE.md asks the model to behave. A hook makes Claude Code behave. "Always run the formatter after editing" is a request the model usually honours and sometimes forgets. A PostToolUse hook on Edit|Write that runs the formatter never forgets, because the model is not involved. Use instructions for judgement and hooks for rules.
Hooks also see things the model never sees. They get the raw tool input before it runs, the session id, the transcript path and the working directory. That makes them the right place for logging, auditing and anything a teammate or another system should hear about.
Example: refuse one kind of command
Hooks live under a hooks key in ~/.claude/settings.json, .claude/settings.json or .claude/settings.local.json, and entries from the different files merge. This one runs a script before every Bash call:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-bash.sh" }]
}
]
}
}
The script reads the event from stdin, finds the command in tool_input.command, and if it matches something you never want run, prints a reason to stderr and exits 2. Claude sees the reason and tries another way. Everything else exits 0 and the command runs as normal.
The matcher is a pattern checked against the tool name: Bash for one tool, Edit|Write for two, mcp__memory__.* for every tool from one MCP server. Anchor it with ^ and `---json
{
"type": "glossary",
"slug": "claude-code-hooks",
"status": "ready",
"move": "cmvpasvog01sz06o4jdvgta6d",
"group": "Coding agents",
"h1": "What are Claude Code hooks?",
"term": "Claude Code hooks",
"title": "Claude Code hooks: run your own code on events",
"description": "Claude Code hooks run your commands, HTTP calls or prompts at points in a session, such as before a tool runs, and can add context or block the action.",
"keywords": [
{
"kw": "claude code hooks",
"vol": 3600
}
],
"answer": "Claude Code hooks are commands, HTTP calls, MCP tools, prompts or subagents that Claude Code runs on its own at set points in a session: before a tool runs, after it finishes, when you submit a prompt, when the agent stops. A hook receives the event as JSON and can observe it, add context, or block it.",
"diagram": {
"caption": "On a matching event Claude Code sends the event JSON to your hook, which runs whatever you wrote and answers with an exit code.",
"nodes": [
{
"id": "when",
"kind": "note",
"label": "on a matching event",
"col": 1,
"row": 0
},
{
"id": "yours",
"kind": "note",
"label": "your code, as you",
"col": 2,
"row": 0
},
{
"id": "you",
"kind": "person",
"label": "you",
"col": 0,
"row": 1
},
{
"id": "claude",
"kind": "box",
"label": "Claude Code",
"sub": "about to run a tool",
"col": 1,
"row": 1
},
{
"id": "hook",
"kind": "box",
"label": "hook",
"sub": "a script, URL or prompt",
"col": 2,
"row": 1
},
{
"id": "target",
"kind": "server",
"label": "linter, log, API, team",
"col": 3,
"row": 1
}
],
"arrows": [
{
"from": "you",
"to": "claude",
"label": "asks for a change"
},
{
"from": "claude",
"to": "hook",
"label": "1. event JSON on stdin",
"bend": -0.15
},
{
"from": "hook",
"to": "target",
"label": "2. does its work"
},
{
"from": "hook",
"to": "claude",
"label": "3. exit 0 allow, 2 block",
"dash": true,
"bend": -0.15
}
]
},
"steps": [
{
"do": "You add a hook in a settings file, a plugin's hooks.json, or a skill's frontmatter: an event name, an optional matcher, and a handler."
},
{
"do": "When the event fires and the matcher matches, Claude Code sends the event as JSON: session id, cwd, and for tool events the tool name and input."
},
{
"do": "Your handler runs. A command hook reads stdin, an HTTP hook receives a POST, and a prompt or agent hook asks a model to decide."
},
{
"do": "Exit 0 means carry on, and any JSON on stdout is applied: a permission decision, extra context, or a rewritten input."
},
{
"do": "Exit 2 blocks the action, with stderr as the reason. Any other code is a non-blocking error: the action goes ahead and the transcript shows a notice."
}
],
"seeAlso": [
"claude-code-plugins",
"agent-skills",
"subagents",
"human-in-the-loop",
"mcp-tools"
],
"source": {
"name": "Claude Code docs: hooks reference",
"url": "https://code.claude.com/docs/en/hooks"
},
"faq": [
{
"q": "Can Claude Code hooks block a command?",
"a": "Yes. A PreToolUse hook that exits with code 2 stops the tool call, and the text it wrote to stderr is shown to Claude as the reason. It can also print JSON with a permissionDecision of allow, deny, ask or defer, which is the cleaner way to express policy."
},
{
"q": "Where do Claude Code hooks run?",
"a": "On the machine running Claude Code, as your user, with your permissions. An HTTP hook is the exception: Claude Code posts the event to a URL and reads the response. Whatever a hook can reach, you can reach, so review hooks from plugins before enabling them."
},
{
"q": "Are Claude Code hooks the same as MCP tools?",
"a": "No. An MCP tool is something Claude chooses to call. A hook is something Claude Code runs for you, whether or not Claude wants it, at a point you picked. A hook can call an MCP tool, which is one of its handler types, but the trigger is the event, not the model."
}
],
"related": [
"integration/claude-code"
],
"redirectFrom": [],
"published": "2026-10-26",
"updated": "2026-10-26",
"notes": [
{
"text": "this card: Claude Code hooks",
"at": [
214,
52
],
"from": [
250,
60
],
"to": [
236,
104
],
"bend": -0.2,
"rot": 2
},
{
"text": "defined, sourced, dated",
"at": [
18,
282
],
"from": [
60,
270
],
"to": [
112,
204
],
"bend": 0.2,
"rot": -2
}
]
}
Hooks versus instructions in CLAUDE.md
A line in CLAUDE.md asks the model to behave. A hook makes Claude Code behave. "Always run the formatter after editing" is a request the model usually honours and sometimes forgets. A PostToolUse hook on Edit|Write that runs the formatter never forgets, because the model is not involved. Use instructions for judgement and hooks for rules.
Hooks also see things the model never sees. They get the raw tool input before it runs, the session id, the transcript path and the working directory. That makes them the right place for logging, auditing and anything a teammate or another system should hear about.
Example: refuse one kind of command
Hooks live under a hooks key in ~/.claude/settings.json, .claude/settings.json or .claude/settings.local.json, and entries from the different files merge. This one runs a script before every Bash call:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-bash.sh" }]
}
]
}
}
The script reads the event from stdin, finds the command in tool_input.command, and if it matches something you never want run, prints a reason to stderr and exits 2. Claude sees the reason and tries another way. Everything else exits 0 and the command runs as normal.
when you need an exact match. Events that have no tool name ignore the matcher.
When to use a hook
The events cover most of a session: SessionStart and SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse and PostToolUseFailure, Stop, SubagentStart and SubagentStop, PreCompact and Notification, among others. Pick the one closest to the moment you care about.
Common uses: format or lint after every edit, forbid commands that touch production, inject the current branch or ticket into context at session start, send a notification when Claude is waiting on you, and keep a record of what the agent did so teammates can see it. Hooks also come in http, mcp_tool, prompt and agent forms, so a check can be a model reading the event rather than a shell script parsing it.
Common mistakes
- Exiting 1 to block. Exit 1 without valid JSON is a non-blocking error: the action goes ahead and you see a notice. Only exit 2, or a JSON deny, stops it.
- Printing a message to stdout and expecting Claude to read it. On a tool event, plain text on stdout is not a decision and does not reach Claude. To give Claude context, print JSON with
additionalContext, written as facts rather than orders.SessionStartandUserPromptSubmitare the exceptions: there, plain stdout is added to context. - Forgetting the default timeout. A command hook has 600 seconds, which is generous for a formatter and far too long for something that hangs. Give hooks that call the network a shorter timeout of their own.
- Doubling up through a plugin. If your settings and a plugin's hooks.json both run the formatter after every edit, you get two formatter runs. Open
/hooksto see everything that is configured before adding more. - Enabling a plugin's hooks unread. They run as you. Read a plugin's hooks.json before enabling it, and set
disableAllHooksto true in your settings to turn every hook off while you investigate.
FAQ
- Can Claude Code hooks block a command?
- Yes. A PreToolUse hook that exits with code 2 stops the tool call, and the text it wrote to stderr is shown to Claude as the reason. It can also print JSON with a permissionDecision of allow, deny, ask or defer, which is the cleaner way to express policy.
- Where do Claude Code hooks run?
- On the machine running Claude Code, as your user, with your permissions. An HTTP hook is the exception: Claude Code posts the event to a URL and reads the response. Whatever a hook can reach, you can reach, so review hooks from plugins before enabling them.
- Are Claude Code hooks the same as MCP tools?
- No. An MCP tool is something Claude chooses to call. A hook is something Claude Code runs for you, whether or not Claude wants it, at a point you picked. A hook can call an MCP tool, which is one of its handler types, but the trigger is the event, not the model.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.