[{"data":1,"prerenderedAt":53},["ShallowReactive",2],{"blog-claude-code-hooks":3,"blog-related-claude-code-hooks":36},{"slug":4,"title":5,"description":6,"category":7,"categoryId":8,"keyword":9,"date":10,"minutes":11,"body":12,"html":13,"headings":14},"claude-code-hooks","Claude Code hooks: run a script on every tool call","Claude Code hooks run your own script before or after a tool call. Learn the config format, exit codes and three working examples you can paste today.","Getting started","getting-started","claude code hooks","2026-11-17",6,"A Claude Code hook is a command you register in `settings.json` that Claude Code itself runs at a fixed point: before a tool call, after an edit, when Claude stops, when it needs your attention. Unlike a line in `CLAUDE.md`, a hook is not a suggestion. The harness executes it every time, whatever the model decided. Use hooks for the rules that cannot have exceptions.\n\n## When should you use a hook instead of CLAUDE.md?\n\nA prompt or a `CLAUDE.md` line is read by the model, and the model usually follows it, but not always. A hook is code that Claude Code runs, so it always happens. Anthropic's own best-practices page puts it this way: if you keep adding emphasis to a `CLAUDE.md` line and Claude still misses it, the line belongs in a hook.\n\nGood candidates:\n\n- Never edit a generated folder or a `.env` file.\n- Always run the formatter after an edit.\n- Don't let Claude finish while the type check fails.\n- Get a desktop notification when Claude is waiting for you.\n\nBad candidates are plain preferences (\"prefer small functions\"). Leave those in [your CLAUDE.md](\u002Fblog\u002Fclaude-md-guide) and let Claude judge.\n\n## What does a hook configuration look like?\n\nHooks live in the `hooks` key of a settings file, in three nested levels: the event, a matcher group, and the handlers to run.\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Edit|Write\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"${CLAUDE_PROJECT_DIR}\u002F.claude\u002Fhooks\u002Fprotect-files.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nWhere you put it decides who gets it:\n\n| File | Scope |\n| --- | --- |\n| `~\u002F.claude\u002Fsettings.json` | All your projects |\n| `.claude\u002Fsettings.json` | This project, committed to git |\n| `.claude\u002Fsettings.local.json` | This project, just you, not committed |\n\nEntries from the different levels are merged. `CLAUDE_PROJECT_DIR` is the project root; use it in paths so the hook works from any working directory. A plugin or a skill can also ship hooks, and a subagent can carry its own that apply only while it runs.\n\n## Which events can you hook into?\n\nThere are more than thirty. The ones you will use first:\n\n| Event | Fires | Can block? |\n| --- | --- | --- |\n| `PreToolUse` | Before a tool runs | Yes |\n| `PostToolUse` | After a tool succeeded | No, the tool already ran |\n| `UserPromptSubmit` | When you send a prompt | Yes |\n| `Stop` | When Claude is about to finish | Yes, it keeps going |\n| `Notification` | When Claude needs your attention | No |\n| `SessionStart` | At the start or resume of a session | No |\n| `SubagentStop` | When a subagent finishes | Yes |\n| `PreCompact` | Before the context is compacted | Yes |\n\nThe full list, including events for worktrees, permission requests and model switches, is on the [hooks reference](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fhooks).\n\n### How does the matcher work?\n\nFor tool events the matcher is matched against the tool name. `\"Bash\"` matches Bash. A list separated by `|` such as `\"Edit|Write\"` matches either one. Leave it out, or use `\"*\"`, to match everything. A matcher that contains any other character is treated as a regular expression, so `mcp__memory__.*` matches every tool of an [MCP server](\u002Fblog\u002Fclaude-code-mcp-servers) called `memory`. Some events, like `UserPromptSubmit` and `Stop`, have no matcher: it is ignored.\n\nTo narrow a handler further, add an `if` field with a permission rule, for example `\"if\": \"Bash(git push *)\"`. It applies to tool events and holds a single rule.\n\n## How does a hook talk to Claude Code?\n\nYour script receives a JSON object on stdin. For a tool event it includes `hook_event_name`, `session_id`, `cwd`, `permission_mode`, `tool_name` and `tool_input`. For an Edit or Write call, `tool_input.file_path` is the file.\n\nIt answers with its exit code:\n\n- **0**: success. Stdout is parsed if it is a single JSON object.\n- **2**: a blocking error. On `PreToolUse` the call is cancelled, and whatever you wrote to stderr is shown to Claude as the reason, so it can adapt.\n- **Anything else, including 1**: a non-blocking error. The action goes ahead and a notice appears. This trips people up: `exit 1` does not enforce anything.\n\nFor finer control, print JSON instead. This denies a call with a reason:\n\n```json\n{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PreToolUse\",\n    \"permissionDecision\": \"deny\",\n    \"permissionDecisionReason\": \"Destructive command blocked by hook\"\n  }\n}\n```\n\n`permissionDecision` also accepts `allow`, `ask` and `defer`.\n\n## Three hooks worth copying\n\n**1. Protect files from edits.** Save as `.claude\u002Fhooks\u002Fprotect-files.sh` and `chmod +x` it:\n\n```sh\n#!\u002Fbin\u002Fbash\nfile=$(jq -r '.tool_input.file_path \u002F\u002F empty')\ncase \"$file\" in\n  *.env|*\u002Fsrc\u002Fgen\u002F*|*package-lock.json)\n    echo \"Blocked: $file is protected. Edit the source instead.\" >&2\n    exit 2 ;;\nesac\nexit 0\n```\n\nRegister it on `PreToolUse` with the matcher `Edit|Write`, as in the configuration above. When Claude tries to touch `.env`, the edit is refused and Claude reads your message and takes another route.\n\n**2. Format after every edit.** On `PostToolUse`, matcher `Edit|Write`:\n\n```json\n{\n  \"type\": \"command\",\n  \"command\": \"jq -r '.tool_input.file_path' | xargs npx prettier --write\"\n}\n```\n\nThe tool has already run, so this cannot block. It just keeps the diff tidy without spending a turn on it.\n\n**3. Notify me when Claude waits.** On `Notification`, on a Mac:\n\n```json\n{\n  \"type\": \"command\",\n  \"command\": \"osascript -e 'display notification \\\"Claude needs you\\\" with title \\\"Claude Code\\\"'\"\n}\n```\n\n### What about the other hook types?\n\n`command` is the default and the most common. There are four others: `http` posts the event JSON to a URL, `mcp_tool` calls a tool of a connected MCP server, `prompt` asks a Claude model a single yes-or-no style question about the event, and `agent` spawns a subagent that can use tools to check a condition (marked experimental). Prompt and agent hooks are useful when the rule is fuzzy (\"does this change touch the public API?\"), at the price of tokens and latency. Command hooks cost nothing but a process.\n\n## How do you debug a hook?\n\n- Type `\u002Fhooks` in a session. It is a read-only browser of every configured hook, with its source file, so you can see why a hook is or isn't there.\n- Run the script by hand with a sample payload: `echo '{\"tool_input\":{\"file_path\":\"a\u002F.env\"}}' | .claude\u002Fhooks\u002Fprotect-files.sh; echo $?`.\n- Remember that hooks for the same event run in parallel, and that the default timeout for a command hook is 600 seconds. Set `timeout` lower for anything that should be quick.\n- A `Stop` hook that exits 2 sends Claude back to work instead of letting it finish, which is how you enforce \"the type check must pass\" (`pnpm tsc --noEmit 1>&2 || exit 2`). Claude Code ends the turn anyway if the hook blocks eight stops in a row with no tool call between them.\n\nTwo cautions. Hooks run with your user's permissions, so treat a hook in a repository you cloned like any other script from that repository. And in non-interactive runs the project's hooks run too, unless you pass `--bare`; see [headless mode](\u002Fblog\u002Fclaude-code-headless-mode) for what that implies in CI. If a hook blocks something you meant to allow, the [permission modes](\u002Fblog\u002Fclaude-code-permission-modes) article explains how rules and hooks combine.\n\n## In Relais\n\nRelais runs your real Claude Code sessions, so hooks you set in `~\u002F.claude\u002Fsettings.json` or in a project's `.claude\u002Fsettings.json` are Claude Code's to run, as in a terminal. Relais adds its own layer around the session (the queue of what needs you, undo, commit and push), described on the [features page](\u002Ffeatures).","\u003Cp>A Claude Code hook is a command you register in \u003Ccode>settings.json\u003C\u002Fcode> that Claude Code itself runs at a fixed point: before a tool call, after an edit, when Claude stops, when it needs your attention. Unlike a line in \u003Ccode>CLAUDE.md\u003C\u002Fcode>, a hook is not a suggestion. The harness executes it every time, whatever the model decided. Use hooks for the rules that cannot have exceptions.\u003C\u002Fp>\n\u003Ch2 id=\"when-should-you-use-a-hook-instead-of-claude-md\">\u003Ca class=\"anchor\" href=\"#when-should-you-use-a-hook-instead-of-claude-md\" aria-label=\"Link to this section\">#\u003C\u002Fa>When should you use a hook instead of CLAUDE.md?\u003C\u002Fh2>\n\u003Cp>A prompt or a \u003Ccode>CLAUDE.md\u003C\u002Fcode> line is read by the model, and the model usually follows it, but not always. A hook is code that Claude Code runs, so it always happens. Anthropic&#39;s own best-practices page puts it this way: if you keep adding emphasis to a \u003Ccode>CLAUDE.md\u003C\u002Fcode> line and Claude still misses it, the line belongs in a hook.\u003C\u002Fp>\n\u003Cp>Good candidates:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Never edit a generated folder or a \u003Ccode>.env\u003C\u002Fcode> file.\u003C\u002Fli>\n\u003Cli>Always run the formatter after an edit.\u003C\u002Fli>\n\u003Cli>Don&#39;t let Claude finish while the type check fails.\u003C\u002Fli>\n\u003Cli>Get a desktop notification when Claude is waiting for you.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Bad candidates are plain preferences (&quot;prefer small functions&quot;). Leave those in \u003Ca href=\"\u002Fblog\u002Fclaude-md-guide\">your CLAUDE.md\u003C\u002Fa> and let Claude judge.\u003C\u002Fp>\n\u003Ch2 id=\"what-does-a-hook-configuration-look-like\">\u003Ca class=\"anchor\" href=\"#what-does-a-hook-configuration-look-like\" aria-label=\"Link to this section\">#\u003C\u002Fa>What does a hook configuration look like?\u003C\u002Fh2>\n\u003Cp>Hooks live in the \u003Ccode>hooks\u003C\u002Fcode> key of a settings file, in three nested levels: the event, a matcher group, and the handlers to run.\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"json\">\u003Ccode>{\n  \u003Cspan class=\"hljs-string\">\"hooks\"\u003C\u002Fspan>: {\n    \u003Cspan class=\"hljs-string\">\"PreToolUse\"\u003C\u002Fspan>: [\n      {\n        \u003Cspan class=\"hljs-string\">\"matcher\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"Edit|Write\"\u003C\u002Fspan>,\n        \u003Cspan class=\"hljs-string\">\"hooks\"\u003C\u002Fspan>: [\n          {\n            \u003Cspan class=\"hljs-string\">\"type\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"command\"\u003C\u002Fspan>,\n            \u003Cspan class=\"hljs-string\">\"command\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"${CLAUDE_PROJECT_DIR}\u002F.claude\u002Fhooks\u002Fprotect-files.sh\"\u003C\u002Fspan>\n          }\n        ]\n      }\n    ]\n  }\n}\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Where you put it decides who gets it:\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>File\u003C\u002Fth>\u003Cth>Scope\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>\u003Ccode>~\u002F.claude\u002Fsettings.json\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>All your projects\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>.claude\u002Fsettings.json\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>This project, committed to git\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>.claude\u002Fsettings.local.json\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>This project, just you, not committed\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>Entries from the different levels are merged. \u003Ccode>CLAUDE_PROJECT_DIR\u003C\u002Fcode> is the project root; use it in paths so the hook works from any working directory. A plugin or a skill can also ship hooks, and a subagent can carry its own that apply only while it runs.\u003C\u002Fp>\n\u003Ch2 id=\"which-events-can-you-hook-into\">\u003Ca class=\"anchor\" href=\"#which-events-can-you-hook-into\" aria-label=\"Link to this section\">#\u003C\u002Fa>Which events can you hook into?\u003C\u002Fh2>\n\u003Cp>There are more than thirty. The ones you will use first:\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>Event\u003C\u002Fth>\u003Cth>Fires\u003C\u002Fth>\u003Cth>Can block?\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>\u003Ccode>PreToolUse\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Before a tool runs\u003C\u002Ftd>\u003Ctd>Yes\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>PostToolUse\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>After a tool succeeded\u003C\u002Ftd>\u003Ctd>No, the tool already ran\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>UserPromptSubmit\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>When you send a prompt\u003C\u002Ftd>\u003Ctd>Yes\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>Stop\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>When Claude is about to finish\u003C\u002Ftd>\u003Ctd>Yes, it keeps going\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>Notification\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>When Claude needs your attention\u003C\u002Ftd>\u003Ctd>No\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>SessionStart\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>At the start or resume of a session\u003C\u002Ftd>\u003Ctd>No\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>SubagentStop\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>When a subagent finishes\u003C\u002Ftd>\u003Ctd>Yes\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>PreCompact\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Before the context is compacted\u003C\u002Ftd>\u003Ctd>Yes\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>The full list, including events for worktrees, permission requests and model switches, is on the \u003Ca href=\"https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fhooks\">hooks reference\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch3 id=\"how-does-the-matcher-work\">\u003Ca class=\"anchor\" href=\"#how-does-the-matcher-work\" aria-label=\"Link to this section\">#\u003C\u002Fa>How does the matcher work?\u003C\u002Fh3>\n\u003Cp>For tool events the matcher is matched against the tool name. \u003Ccode>&quot;Bash&quot;\u003C\u002Fcode> matches Bash. A list separated by \u003Ccode>|\u003C\u002Fcode> such as \u003Ccode>&quot;Edit|Write&quot;\u003C\u002Fcode> matches either one. Leave it out, or use \u003Ccode>&quot;*&quot;\u003C\u002Fcode>, to match everything. A matcher that contains any other character is treated as a regular expression, so \u003Ccode>mcp__memory__.*\u003C\u002Fcode> matches every tool of an \u003Ca href=\"\u002Fblog\u002Fclaude-code-mcp-servers\">MCP server\u003C\u002Fa> called \u003Ccode>memory\u003C\u002Fcode>. Some events, like \u003Ccode>UserPromptSubmit\u003C\u002Fcode> and \u003Ccode>Stop\u003C\u002Fcode>, have no matcher: it is ignored.\u003C\u002Fp>\n\u003Cp>To narrow a handler further, add an \u003Ccode>if\u003C\u002Fcode> field with a permission rule, for example \u003Ccode>&quot;if&quot;: &quot;Bash(git push *)&quot;\u003C\u002Fcode>. It applies to tool events and holds a single rule.\u003C\u002Fp>\n\u003Ch2 id=\"how-does-a-hook-talk-to-claude-code\">\u003Ca class=\"anchor\" href=\"#how-does-a-hook-talk-to-claude-code\" aria-label=\"Link to this section\">#\u003C\u002Fa>How does a hook talk to Claude Code?\u003C\u002Fh2>\n\u003Cp>Your script receives a JSON object on stdin. For a tool event it includes \u003Ccode>hook_event_name\u003C\u002Fcode>, \u003Ccode>session_id\u003C\u002Fcode>, \u003Ccode>cwd\u003C\u002Fcode>, \u003Ccode>permission_mode\u003C\u002Fcode>, \u003Ccode>tool_name\u003C\u002Fcode> and \u003Ccode>tool_input\u003C\u002Fcode>. For an Edit or Write call, \u003Ccode>tool_input.file_path\u003C\u002Fcode> is the file.\u003C\u002Fp>\n\u003Cp>It answers with its exit code:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>0\u003C\u002Fstrong>: success. Stdout is parsed if it is a single JSON object.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>2\u003C\u002Fstrong>: a blocking error. On \u003Ccode>PreToolUse\u003C\u002Fcode> the call is cancelled, and whatever you wrote to stderr is shown to Claude as the reason, so it can adapt.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Anything else, including 1\u003C\u002Fstrong>: a non-blocking error. The action goes ahead and a notice appears. This trips people up: \u003Ccode>exit 1\u003C\u002Fcode> does not enforce anything.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>For finer control, print JSON instead. This denies a call with a reason:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"json\">\u003Ccode>{\n  \u003Cspan class=\"hljs-string\">\"hookSpecificOutput\"\u003C\u002Fspan>: {\n    \u003Cspan class=\"hljs-string\">\"hookEventName\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"PreToolUse\"\u003C\u002Fspan>,\n    \u003Cspan class=\"hljs-string\">\"permissionDecision\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"deny\"\u003C\u002Fspan>,\n    \u003Cspan class=\"hljs-string\">\"permissionDecisionReason\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"Destructive command blocked by hook\"\u003C\u002Fspan>\n  }\n}\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>permissionDecision\u003C\u002Fcode> also accepts \u003Ccode>allow\u003C\u002Fcode>, \u003Ccode>ask\u003C\u002Fcode> and \u003Ccode>defer\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"three-hooks-worth-copying\">\u003Ca class=\"anchor\" href=\"#three-hooks-worth-copying\" aria-label=\"Link to this section\">#\u003C\u002Fa>Three hooks worth copying\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>1. Protect files from edits.\u003C\u002Fstrong> Save as \u003Ccode>.claude\u002Fhooks\u002Fprotect-files.sh\u003C\u002Fcode> and \u003Ccode>chmod +x\u003C\u002Fcode> it:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>#!\u002Fbin\u002Fbash\nfile=$(jq -r '.tool_input.file_path \u002F\u002F empty')\ncase &quot;$file&quot; in\n  *.env|*\u002Fsrc\u002Fgen\u002F*|*package-lock.json)\n    echo &quot;Blocked: $file is protected. Edit the source instead.&quot; &gt;&amp;2\n    exit 2 ;;\nesac\nexit 0\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Register it on \u003Ccode>PreToolUse\u003C\u002Fcode> with the matcher \u003Ccode>Edit|Write\u003C\u002Fcode>, as in the configuration above. When Claude tries to touch \u003Ccode>.env\u003C\u002Fcode>, the edit is refused and Claude reads your message and takes another route.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>2. Format after every edit.\u003C\u002Fstrong> On \u003Ccode>PostToolUse\u003C\u002Fcode>, matcher \u003Ccode>Edit|Write\u003C\u002Fcode>:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"json\">\u003Ccode>{\n  \u003Cspan class=\"hljs-string\">\"type\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"command\"\u003C\u002Fspan>,\n  \u003Cspan class=\"hljs-string\">\"command\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"jq -r '.tool_input.file_path' | xargs npx prettier --write\"\u003C\u002Fspan>\n}\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The tool has already run, so this cannot block. It just keeps the diff tidy without spending a turn on it.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>3. Notify me when Claude waits.\u003C\u002Fstrong> On \u003Ccode>Notification\u003C\u002Fcode>, on a Mac:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"json\">\u003Ccode>{\n  \u003Cspan class=\"hljs-string\">\"type\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"command\"\u003C\u002Fspan>,\n  \u003Cspan class=\"hljs-string\">\"command\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"osascript -e 'display notification \\\"Claude needs you\\\" with title \\\"Claude Code\\\"'\"\u003C\u002Fspan>\n}\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3 id=\"what-about-the-other-hook-types\">\u003Ca class=\"anchor\" href=\"#what-about-the-other-hook-types\" aria-label=\"Link to this section\">#\u003C\u002Fa>What about the other hook types?\u003C\u002Fh3>\n\u003Cp>\u003Ccode>command\u003C\u002Fcode> is the default and the most common. There are four others: \u003Ccode>http\u003C\u002Fcode> posts the event JSON to a URL, \u003Ccode>mcp_tool\u003C\u002Fcode> calls a tool of a connected MCP server, \u003Ccode>prompt\u003C\u002Fcode> asks a Claude model a single yes-or-no style question about the event, and \u003Ccode>agent\u003C\u002Fcode> spawns a subagent that can use tools to check a condition (marked experimental). Prompt and agent hooks are useful when the rule is fuzzy (&quot;does this change touch the public API?&quot;), at the price of tokens and latency. Command hooks cost nothing but a process.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-debug-a-hook\">\u003Ca class=\"anchor\" href=\"#how-do-you-debug-a-hook\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you debug a hook?\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>Type \u003Ccode>\u002Fhooks\u003C\u002Fcode> in a session. It is a read-only browser of every configured hook, with its source file, so you can see why a hook is or isn&#39;t there.\u003C\u002Fli>\n\u003Cli>Run the script by hand with a sample payload: \u003Ccode>echo &#39;{&quot;tool_input&quot;:{&quot;file_path&quot;:&quot;a\u002F.env&quot;}}&#39; | .claude\u002Fhooks\u002Fprotect-files.sh; echo $?\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>Remember that hooks for the same event run in parallel, and that the default timeout for a command hook is 600 seconds. Set \u003Ccode>timeout\u003C\u002Fcode> lower for anything that should be quick.\u003C\u002Fli>\n\u003Cli>A \u003Ccode>Stop\u003C\u002Fcode> hook that exits 2 sends Claude back to work instead of letting it finish, which is how you enforce &quot;the type check must pass&quot; (\u003Ccode>pnpm tsc --noEmit 1&gt;&amp;2 || exit 2\u003C\u002Fcode>). Claude Code ends the turn anyway if the hook blocks eight stops in a row with no tool call between them.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Two cautions. Hooks run with your user&#39;s permissions, so treat a hook in a repository you cloned like any other script from that repository. And in non-interactive runs the project&#39;s hooks run too, unless you pass \u003Ccode>--bare\u003C\u002Fcode>; see \u003Ca href=\"\u002Fblog\u002Fclaude-code-headless-mode\">headless mode\u003C\u002Fa> for what that implies in CI. If a hook blocks something you meant to allow, the \u003Ca href=\"\u002Fblog\u002Fclaude-code-permission-modes\">permission modes\u003C\u002Fa> article explains how rules and hooks combine.\u003C\u002Fp>\n\u003Ch2 id=\"in-relais\">\u003Ca class=\"anchor\" href=\"#in-relais\" aria-label=\"Link to this section\">#\u003C\u002Fa>In Relais\u003C\u002Fh2>\n\u003Cp>Relais runs your real Claude Code sessions, so hooks you set in \u003Ccode>~\u002F.claude\u002Fsettings.json\u003C\u002Fcode> or in a project&#39;s \u003Ccode>.claude\u002Fsettings.json\u003C\u002Fcode> are Claude Code&#39;s to run, as in a terminal. Relais adds its own layer around the session (the queue of what needs you, undo, commit and push), described on the \u003Ca href=\"\u002Ffeatures\">features page\u003C\u002Fa>.\u003C\u002Fp>\n",[15,18,21,24,27,30,33],{"id":16,"text":17},"when-should-you-use-a-hook-instead-of-claude-md","When should you use a hook instead of CLAUDE.md?",{"id":19,"text":20},"what-does-a-hook-configuration-look-like","What does a hook configuration look like?",{"id":22,"text":23},"which-events-can-you-hook-into","Which events can you hook into?",{"id":25,"text":26},"how-does-a-hook-talk-to-claude-code","How does a hook talk to Claude Code?",{"id":28,"text":29},"three-hooks-worth-copying","Three hooks worth copying",{"id":31,"text":32},"how-do-you-debug-a-hook","How do you debug a hook?",{"id":34,"text":35},"in-relais","In Relais",[37,43,48],{"slug":38,"title":39,"description":40,"category":7,"categoryId":8,"keyword":41,"date":10,"minutes":42},"claude-code-beginners-guide","Claude Code for beginners: install, first session, habits","Install Claude Code, run your first session and learn the habits that matter: specific prompts, plan before edit, CLAUDE.md, small commits, a clean context.","claude code for beginners",5,{"slug":44,"title":45,"description":46,"category":7,"categoryId":8,"keyword":47,"date":10,"minutes":42},"claude-code-permission-modes","Claude Code permission modes explained (and when to use each)","Default, acceptEdits, plan, auto, dontAsk and bypassPermissions: what each Claude Code permission mode allows, how to switch, and which one fits which job.","claude code permission modes",{"slug":49,"title":50,"description":51,"category":7,"categoryId":8,"keyword":52,"date":10,"minutes":42},"claude-code-skills","Claude Code skills: what they are and how to write one","A Claude Code skill is a folder with a SKILL.md that Claude loads when relevant or you call with a slash. See the format, frontmatter fields and an example.","claude code skills",1794931098787]