project Claude Code config<\/a>. Open the shared project file:<\/p>\n\n\nvim .claude\/settings.json<\/code><\/pre>\n\n\nThe structure nests three levels deep: the hooks<\/code> key, then the event name, then an array of matcher groups, each holding the actual hooks to run. A minimal example that echoes a line every time Claude edits or writes a file:<\/p>\n\n\n{\n \"hooks\": {\n \"PostToolUse\": [\n {\n \"matcher\": \"Edit|Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo \\\"Claude touched a file at $(date)\\\" >> ~\/claude-edits.log\"\n }\n ]\n }\n ]\n }\n}<\/code><\/pre>\n\n\nOne operational note that saves confusion: edits to a hook in your settings files are picked up automatically by Claude Code’s file watcher, so a change usually takes effect without restarting the session. The \/hooks<\/code> menu is a read-only view of what is currently wired up, handy for confirming a hook registered, but you make changes by editing the JSON, not from that menu. If you ever need to switch every hook off at once, set \"disableAllHooks\": true<\/code> in settings rather than deleting them.<\/p>\n\nMatching the right events<\/h2>\n\n The matcher<\/code> field decides which occurrences of an event a hook group responds to, and how it is read depends entirely on the characters inside it. A value of *<\/code>, an empty string, or an omitted matcher fires on every occurrence. A value containing only letters, digits, underscores, and the pipe is treated as an exact string or a pipe-separated list of exact strings, so Bash<\/code> matches only the Bash tool and Edit|Write<\/code> matches either one. Anything with another character in it becomes a JavaScript regular expression.<\/p>\n\nThat last rule is the source of a real gotcha with MCP tools. MCP tool names follow the pattern mcp__<server>__<tool><\/code>, and to match every tool from one server you have to append .*<\/code>, because a bare mcp__memory<\/code> contains only letters and underscores and is therefore compared as an exact string that matches nothing:<\/p>\n\n\n\"matcher\": \"mcp__memory__.*\"<\/code><\/pre>\n\n\nFor finer control on tool events, there is a second filter. The if<\/code> field takes permission-rule syntax and runs the hook only when the tool call matches, so you can scope a hook to a narrow case without writing the matching logic yourself:<\/p>\n\n\n\"if\": \"Bash(git push *)\"<\/code><\/pre>\n\n\nThe catch worth remembering is that if<\/code> is only evaluated on the tool events, namely PreToolUse<\/code>, PostToolUse<\/code>, PostToolUseFailure<\/code>, PermissionRequest<\/code>, and PermissionDenied<\/code>. Put it on any other event and the hook never runs.<\/p>\n\nWhat your hook receives, and how it answers<\/h2>\n\n Every hook gets a JSON object on standard input. The common fields are present on every event: session_id<\/code>, transcript_path<\/code>, cwd<\/code>, permission_mode<\/code>, and hook_event_name<\/code>. Tool events add the ones you usually care about, tool_name<\/code> and tool_input<\/code>; events firing in a tool-use context also carry effort<\/code> (an object whose level<\/code> field holds the active effort), and hooks firing inside a subagent carry agent_id<\/code> and agent_type<\/code>. A PreToolUse<\/code> payload for a Bash call looks like this:<\/p>\n\n\n{\n \"session_id\": \"abc123\",\n \"cwd\": \"\/home\/user\/my-project\",\n \"permission_mode\": \"default\",\n \"hook_event_name\": \"PreToolUse\",\n \"tool_name\": \"Bash\",\n \"tool_input\": { \"command\": \"rm -rf \/tmp\/build\" }\n}<\/code><\/pre>\n\n\nThe hook answers in one of two ways, and the simplest is the exit code. Exit 0<\/code> means success, and Claude Code parses standard out for any JSON instructions. Exit 2<\/code> is the blocking signal: Claude Code discards stdout and feeds your stderr text back to the model as the reason the action was stopped. Every other exit code is treated as a non-blocking error, the action proceeds, and a notice shows in the transcript. The trap that catches people is that exit 1<\/code>, the conventional Unix failure code, does not<\/strong> block. If a hook is meant to enforce a policy, it has to exit 2<\/code>.<\/p>\n\nThere is one more useful behavior tied to standard out. For most events stdout only goes to the debug log, but for UserPromptSubmit<\/code>, UserPromptExpansion<\/code>, and SessionStart<\/code> it is added straight into the context as something Claude can read and act on. That is the mechanism behind context-injection hooks, where a script prints the current ticket number or git branch and Claude picks it up without you typing it.<\/p>\n\nTelling Claude exactly what to do<\/h2>\n\n Exit codes are blunt. For precise control, a hook exits 0<\/code> and prints JSON, and this is the layer most guides skip. A set of universal fields works on any event: continue<\/code> to halt all processing (with stopReason<\/code> as the message shown when it does), systemMessage<\/code> to surface a warning to the user, suppressOutput<\/code> to hide the hook’s stdout, and terminalSequence<\/code> to emit a desktop notification or set the window title.<\/p>\n\nBeyond those, the decision shape differs by event, which is the nuance worth getting right. Most events that can steer Claude use a top-level decision<\/code>, for example UserPromptSubmit<\/code>, PostToolUse<\/code>, and Stop<\/code>:<\/p>\n\n\n{ \"decision\": \"block\", \"reason\": \"Commit message is missing a ticket reference.\" }<\/code><\/pre>\n\n\nPreToolUse<\/code> is the exception and the one you will reach for most, because it carries a real permission decision rather than a yes or no. It returns a hookSpecificOutput<\/code> with a permissionDecision<\/code> of allow<\/code>, deny<\/code>, ask<\/code>, or defer<\/code>:<\/p>\n\n\n{\n \"hookSpecificOutput\": {\n \"hookEventName\": \"PreToolUse\",\n \"permissionDecision\": \"deny\",\n \"permissionDecisionReason\": \"Destructive command blocked by hook\"\n }\n}<\/code><\/pre>\n\n\nThe difference matters in practice. allow<\/code> skips the normal permission prompt entirely, ask<\/code> forces one, and deny<\/code> stops the call with your reason handed to the model. We would reach for the JSON form over a bare exit 2<\/code> whenever the reason needs to be specific enough for Claude to act on, and for the cheap “block anything that looks like X” guards, exit 2<\/code> with a stderr message is less code.<\/p>\n\nFive kinds of hook handler<\/h2>\n\n The type<\/code> field is not limited to shell commands, though that is where almost everyone starts. There are five handler types, and the two that older guides miss are exactly the ones that open up the interesting designs:<\/p>\n\n\nType<\/th> What it does<\/th> Reach for it when<\/th><\/tr><\/thead> \ncommand<\/code><\/td>Runs a shell command with the event JSON on stdin<\/td> The default, for scripts and CLI tools<\/td><\/tr>\n http<\/code><\/td>POSTs the event JSON to a URL<\/td> Centralized logging or a policy service<\/td><\/tr>\n mcp_tool<\/code><\/td>Calls a tool on a connected MCP server<\/td> You already run an MCP server that can act<\/td><\/tr>\n prompt<\/code><\/td>Sends a single-turn prompt to a model for a verdict<\/td> The check needs judgment, not a regex<\/td><\/tr>\n agent<\/code><\/td>Spawns a subagent with tools like Read and Grep<\/td> The check needs to investigate the codebase<\/td><\/tr>\n<\/tbody><\/table><\/figure>\n\n\nThe prompt<\/code> and agent<\/code> handlers are the genuinely new design space. A prompt<\/code> hook on UserPromptSubmit<\/code> can have a cheap model judge whether a request looks risky before the main model ever sees it, and an agent<\/code> hook can actually go read files to make its decision. Most production setups still lean on command<\/code>, because a shell script is predictable and free, but the option to escalate to a model is there when the rule cannot be expressed as a pattern.<\/p>\n\nA hook that blocks a destructive command<\/h2>\n\n Theory settles into place once a hook stops something real. Here is a PreToolUse<\/code> hook scoped to the Bash tool, wired into .claude\/settings.json<\/code> and pointed at a small script. The script reads the proposed command off stdin and exits 2<\/code> if it spots a recursive force-delete:<\/p>\n\n\nTo make the point unmissable, we ran Claude with --dangerously-skip-permissions<\/code>, which turns off the permission system entirely, then asked it to delete a directory with rm -rf<\/code>. With permissions off, the hook is the only thing standing in the way. It held: the command was blocked, the stderr reason went back to the model, and the build<\/code> directory was still there afterward.<\/p>\n\n\nOne honest lesson came out of testing that is worth more than the success itself. On an earlier run, the hook blocked rm -rf build<\/code>, and Claude deleted the file explicitly and then ran rmdir<\/code>, a path the regex did not catch. The takeaway shapes how you write these: scope a guard to the behavior you fear, not to one spelling of one command, and treat hooks as a layer alongside the permission system rather than a replacement for it. A hook that only knows rm -rf<\/code> is a speed bump, not a wall.<\/p>\n\nMore patterns worth wiring in<\/h2>\n\n The same machinery covers most of what teams actually automate. Auto-formatting on edit is the canonical PostToolUse<\/code> hook, matched to the file-editing tools so a formatter runs the moment Claude changes code:<\/p>\n\n\n{\n \"hooks\": {\n \"PostToolUse\": [\n {\n \"matcher\": \"Edit|Write\",\n \"hooks\": [\n { \"type\": \"command\", \"command\": \"$CLAUDE_PROJECT_DIR\/.claude\/hooks\/format-changed.sh\" }\n ]\n }\n ]\n }\n}<\/code><\/pre>\n\n\nContext injection is the UserPromptSubmit<\/code> pattern, where a script prints something useful and Claude reads it because stdout on that event becomes context. A script that echoes the current git branch and open ticket, for instance, means you stop pasting that detail into every prompt. And for ambient awareness, a Notification<\/code> hook that emits a terminalSequence<\/code> fires a desktop alert when Claude needs your attention, so a long run does not sit waiting silently while you have switched windows.<\/p>\n\nHow we run hooks in production<\/h2>\n\n We lean on this system hard for our own publishing pipeline, and the shape is worth sharing because it is the pattern most worth copying. Every article on this site goes through a publish step, and a PreToolUse<\/code> hook on the Bash tool inspects that command before it runs. If the command is a publish and the article has not passed its checks, missing meta, an unverified review, a too-short body, the hook exits 2<\/code> and the publish never happens. The operator sees exactly why and fixes it.<\/p>\n\nThe trade-off we made there is the one to think through for any enforcement hook. A deterministic gate is stricter than trusting whoever is at the keyboard, and that strictness is the entire value: it means a rule cannot be skipped on a tired afternoon. The cost is that the gate has to be correct, because a buggy hook blocks legitimate work as reliably as it blocks mistakes. We keep ours narrow and loud, each one checking a single condition and printing a precise reason, which is the same discipline that keeps a subagent or a CI check maintainable. For teams already running Claude Code in their CI and infrastructure<\/a> workflows, hooks are the local equivalent of a pre-commit gate.<\/p>\n\nReady-made hooks from the community<\/h2>\n\n You do not have to write everything yourself. A few collections are worth raiding for working scripts (star counts approximate, as of June 2026):<\/p>\n\n\n
\ndisler\/claude-code-hooks-mastery<\/code> (~4K) is the canonical teaching repo, with a standalone script per event and a logging hook for every one. It is the best place to see the full surface in action, though it ships without a clear license, so read before you reuse.<\/li>\ncarlrannaberg\/claudekit<\/code> (~700, MIT) is a production toolkit of typecheck, lint, and test-on-change hooks plus a git checkpoint on stop.<\/li>\nnizos\/tdd-guard<\/code> (~2K, MIT) enforces test-driven development by blocking implementation before a failing test exists.<\/li>\nhesreallyhim\/awesome-claude-code<\/code> (~46K) is the umbrella list and the hub to track the rest of the ecosystem.<\/li>\n<\/ul>\n\n\nTreat anything you copy the way you would treat any script that runs with your privileges, because that is exactly what a hook is.<\/p>\n\n
Running hooks safely in production<\/h2>\n\n That last point is the one to close on, because it is where hooks differ from the rest of your Claude Code config. A hook is arbitrary code that Claude Code executes automatically with your full permissions, so the security posture has to match. A short checklist keeps it honest: read every hook before you trust it, and be especially careful with project hooks from a repo you cloned. Reference scripts through $CLAUDE_PROJECT_DIR<\/code> rather than absolute paths so they stay portable. Remember that a personal ~\/.claude\/settings.json<\/code> hook follows you into every project, including ones you did not write. Give long-running hooks a sensible timeout<\/code> so a hung script does not stall the session. And keep the exit-code contract in muscle memory, since an enforcement hook that exits 1<\/code> instead of 2<\/code> looks like it is working while quietly letting everything through.<\/p>\n\nGet those habits right and hooks become the most reliable part of your setup, the layer that does not depend on the model remembering anything. Pin the events table next to your Claude Code cheat sheet<\/a>, start with one PostToolUse<\/code> formatter and one PreToolUse<\/code> guard, and grow the set as you find the seams in your own workflow where a guarantee beats a suggestion.<\/p>","protected":false},"excerpt":{"rendered":"Before you wire up a single hook, the question worth settling is what you actually want them for. A prompt in your CLAUDE.md asking Claude to run the linter after edits is a suggestion the model can forget. A hook that runs the linter after every edit is a guarantee, because Claude Code runs it, … Read more<\/a><\/p>\n","protected":false},"author":17,"featured_media":168732,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[39034,690,299],"tags":[17245,212,669,211],"cfg_series":[39880],"class_list":["post-168731","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai","category-dev","category-how-to","tag-ai","tag-automation","tag-dev","tag-devops","cfg_series-claude-code-mastery"],"_links":{"self":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/168731","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/users\/17"}],"replies":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/comments?post=168731"}],"version-history":[{"count":2,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/168731\/revisions"}],"predecessor-version":[{"id":168735,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/168731\/revisions\/168735"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media\/168732"}],"wp:attachment":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media?parent=168731"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/categories?post=168731"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/tags?post=168731"},{"taxonomy":"cfg_series","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/cfg_series?post=168731"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
![\"A](\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/06\/wm-claude-code-hooks-pretooluse-settings-json.png\" "\\"\\"")
<\/figure>\n\n\n![\"A](\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/06\/wm-claude-code-hooks-block-dangerous-command.png\" "\\"\\"")
<\/figure>\n\n\n