Confession. I spent about three weeks pretending Claude Code hooks were a nice-to-have. I read the docs, nodded, and went back to babysitting every agent run like a manager who won’t stop hovering.<\/p>\n
Then I let an agent commit a That was the day I stopped pretending. I opened This post walks through the exact hook setup I ship in every project. The shape of the JSON that comes in on stdin. The exit codes that actually block a tool call. A couple of gotchas that cost me an evening each. If you’re new to Claude Code hooks, this is the mental model I wish someone had handed me first.<\/p>\n Strip the marketing. A Claude Code hook is a shell command that runs when the agent hits a specific lifecycle event. You wire them up in Every hook gets a JSON payload on stdin. For a tool event you get the tool name, the tool input, the session id, the cwd, and a transcript path. Your script reads it, decides what to do, and communicates back through exit codes or structured JSON on stdout.<\/p>\n Two things you have to know before you write your first one:<\/p>\n That’s basically the whole primitive. Everything else is convention. The full event list and payload schema live in the Claude Code hooks reference<\/a>, and the file locations are covered in the settings docs<\/a>.<\/p>\n Here’s my baseline. Nothing fancy. It has saved me from the two failure modes I actually hit: writing secrets to disk, and shipping unformatted code.<\/p>\n Before I let Claude Code touch a file, I check the path against a small deny list. If it matches, block.<\/p>\n Old way, back when I was doing this by hand:<\/p>\n That was the “system.” Predictably, I forgot to send the message once.<\/p>\n New way, in And the script it points at:<\/p>\n Exit code This one nobody talks about, but I use it every day. When Claude Code writes or edits a JS\/TS file, I want Prettier and ESLint to run on it immediately, and I want lint failures to feed back into the agent so it fixes its own mess.<\/p>\n And the script:<\/p>\n The trick is The real payoff isn’t the automation itself, though that’s nice. What I actually notice is that the agent stops asking me every three minutes whether to run the formatter. It just does, because the hook already did.<\/p>\n I lost about an evening each to these. Save yourself.<\/p>\n First, hooks run in your shell, not Claude Code’s process. That means Second, stderr is the message and stdout is protocol. If you want to talk to the agent, write to stderr and exit Third, matchers are regex over tool names, not glob patterns over file paths. Fourth, global settings are less sandboxed than you think. If you put a hook in Rigorous mentor mode: this isn’t a silver bullet. There are two situations where I turn hooks off.<\/p>\n Prototyping in a throwaway branch where I want to see what the agent produces raw. If the lint hook blocks every third tool call while I’m trying to explore an API, I lose the rhythm. In that case I switch the branch to a “no-hooks” mode with a local override file and just eyeball things until the shape is clearer.<\/p>\n Slash commands and MCP-based tools that don’t map cleanly to the matcher regex. Some MCP servers surface names your regex won’t anticipate. The workaround is to broaden the matcher and filter inside the script by inspecting the payload. It works, but it’s less clean, and if I only have one flaky MCP I’ll usually just not hook it at all.<\/p>\n If you’re deciding whether hooks or a different tool fits your workflow, you might want to skim my longer take in Codex vs Claude Code<\/a>. Different tools, different guardrail stories. I also keep a running set of hook scripts and prompt patterns I actually ship on my portfolio<\/a>; grab whatever bits are useful.<\/p>\n If you have twenty minutes this week, here is the order I would do it in.<\/p>\n Create Start the deny list minimal. Wire the formatter to Log every hook invocation to a file for the first week. Something like Then delete the ones that never fired.<\/p>\n That is it. No magic. Just a small pile of shell scripts that make the agent behave the way I would want a careful new hire to behave: don’t touch the secrets, format the code, tell me when something’s wrong. If your agent runs still feel like babysitting, this is where I would start.<\/p>\n","protected":false},"excerpt":{"rendered":" Claude Code hooks changed how I run agents. Here is the exact PreToolUse and PostToolUse setup I ship in every repo, with the JSON, exit codes, and traps.<\/p>\n","protected":false},"author":2,"featured_media":429,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"Claude Code hooks changed how I run agents. Here is the exact PreToolUse and PostToolUse setup I ship in every repo, with the JSON, exit codes, and traps.","rank_math_focus_keyword":"claude code hooks","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[4,184],"tags":[363,424,27,467,108,468,425,69],"class_list":["post-430","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai","category-developer-tools","tag-ai-agents","tag-ai-coding-2","tag-automation","tag-claude","tag-claude-code","tag-cli","tag-developer-tools-2","tag-hooks"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/430","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=430"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/430\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/429"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=430"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=430"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=430"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}.env<\/code> file to a public repo.<\/p>\n~\/.claude\/settings.json<\/code>, wrote a five-line PreToolUse hook, and haven’t lost sleep about accidental commits since. Hooks aren’t a nice-to-have. They’re the difference between “I let the agent work” and “I sit here watching every diff scroll by, defeating the whole point of hiring a helper in the first place.”<\/p>\nWhat Claude Code hooks actually are<\/h2>\n
.claude\/settings.json<\/code> (per project) or ~\/.claude\/settings.json<\/code> (global). The events I use most are PreToolUse<\/code> and PostToolUse<\/code>, but there are others: UserPromptSubmit<\/code>, SessionStart<\/code>, Stop<\/code>, SubagentStop<\/code>, Notification<\/code>.<\/p>\n\n
2<\/code> blocks the tool call and sends your stderr back to the agent as a message. Exit code 0<\/code> is a pass. Anything else is a non-blocking error the user sees but the agent ignores.<\/li>\n{\"decision\": \"block\", \"reason\": \"...\"}<\/code> on stdout for the same effect, plus richer control on PreToolUse<\/code> (allow, ask, block).<\/li>\n<\/ul>\nThe two hooks I run in every repo<\/h2>\n
PreToolUse: block writes to sensitive files<\/h3>\n
# Me, in a real Slack message to a coworker, three months ago:\n# "hey can you also check that Claude didn't touch .env or ~\/.ssh or anything\n# in secrets\/ before you merge my PR"\n<\/code><\/pre>\n.claude\/settings.json<\/code>:<\/p>\n{\n "hooks": {\n "PreToolUse": [\n {\n "matcher": "Write|Edit|MultiEdit",\n "hooks": [\n {\n "type": "command",\n "command": "python3 .claude\/guardrails\/block_secrets.py"\n }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n#!\/usr\/bin\/env python3\nimport json, sys, re, os\n\nDENY = [\n r"\\.env(\\..+)?$",\n r"\\.pem$",\n r"id_rsa(\\.pub)?$",\n r"secrets\/.*",\n r"credentials\\.json$",\n]\n\npayload = json.load(sys.stdin)\ntool_input = payload.get("tool_input", {})\npath = tool_input.get("file_path") or tool_input.get("path") or ""\nrel = os.path.relpath(path, payload.get("cwd", "."))\n\nfor pat in DENY:\n if re.search(pat, rel):\n print(\n f"Refused to touch {rel}. Update block_secrets.py to allow.",\n file=sys.stderr,\n )\n sys.exit(2)\n\nsys.exit(0)\n<\/code><\/pre>\n2<\/code> blocks the write and hands the message to the agent, which then explains it to me instead of surprising me on git diff<\/code>. Ten minutes of setup, no more panicked “did I check .env<\/code> this time” thoughts.<\/p>\nPostToolUse: run the formatter and lint<\/h3>\n
{\n "hooks": {\n "PostToolUse": [\n {\n "matcher": "Write|Edit|MultiEdit",\n "hooks": [\n {\n "type": "command",\n "command": "bash .claude\/guardrails\/format_and_lint.sh"\n }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n#!\/usr\/bin\/env bash\nset -e\npayload="$(cat)"\nfile="$(echo "$payload" | jq -r '.tool_input.file_path \/\/ .tool_input.path \/\/ empty')"\n\ncase "$file" in\n *.ts|*.tsx|*.js|*.jsx)\n npx prettier --write "$file" >\/dev\/null\n if ! npx eslint --max-warnings=0 "$file" 1>&2; then\n echo "Lint failed on $file. Fix warnings before continuing." 1>&2\n exit 2\n fi\n ;;\nesac\n<\/code><\/pre>\nexit 2<\/code> on lint failure. Claude Code sees the message, treats it as a tool-use error, and iterates. I’ve watched it clean up its own unused imports about ten times this week without me typing a word.<\/p>\nThe gotchas nobody documents<\/h2>\n
$PATH<\/code> behaves like a login shell in most cases, but not always. If your hook depends on nvm<\/code>, pyenv<\/code>, or a specific venv, source the activation script inside the hook or use absolute paths. Debugging a hook that “works in my terminal” but fails silently in the agent is not how I want to spend a Saturday.<\/p>\n2<\/code>, or print structured JSON on stdout. Mixing them, or printing plain text on stdout, gets you either silence or a confused agent. I misread this on my first attempt and thought hooks didn’t work at all.<\/p>\n\"matcher\": \"Write|Edit\"<\/code> matches the tool names Write<\/code> and Edit<\/code>. If you want to filter by file, do that inside your script (like the case \"$file\" in<\/code> block above). The docs are clear enough about this in hindsight, but I definitely wasted twenty minutes staring at \"matcher\": \"*.env\"<\/code> wondering why it wasn’t firing.<\/p>\n~\/.claude\/settings.json<\/code>, it runs for every project. Convenient for the secrets blocker. Terrible for a repo-specific lint config that assumes a Node project when you’re currently in a Rust one. Keep per-project scripts under .claude\/<\/code> in the repo, and only put truly cross-cutting rules in the global config.<\/p>\nWhen I don’t use hooks<\/h2>\n
The setup I’d copy if I were you today<\/h2>\n
.claude\/settings.json<\/code> in your project with both a PreToolUse<\/code> block for a secrets deny list and a PostToolUse<\/code> block for your language’s formatter. Point them at scripts under .claude\/guardrails\/<\/code> so they live in git and travel with the repo.<\/p>\n.env<\/code>, id_rsa<\/code>, secrets\/<\/code>. You can grow it later. A short list you actually maintain beats a long one you copy-pasted from a gist and never audited.<\/p>\nexit 2<\/code> on real failures, not on style warnings. If you make it too aggressive it will block the agent constantly and you will turn it off inside a day. Aim for block on lint errors and warn on style, not the reverse.<\/p>\n>> .claude\/guardrails\/hook.log 2>&1<\/code> at the end of each command. Read the log on Friday. You will see which hooks fire, which never do, and which are catching real mistakes versus creating friction.<\/p>\n