The hooks worth running on a website repository

An agent that can edit your repository will eventually edit it wrongly. Not often, and rarely in a way that looks wrong in the diff, but often enough that reading every change yourself defeats the point of having an agent at all. The answer is not more careful reading. It is a gate: a script that runs on its own at a fixed point in the session and refuses the change when it fails. Claude Code calls these hooks, and on a website repository three of them do most of the work.

A hook is a shell command with an opinion

A hook is a command Claude Code runs at a named point in the session, with JSON about what just happened arriving on stdin. Your script reads that JSON, decides, and answers through its exit code. Exit 0 means no opinion and the action proceeds through the normal permission flow. Exit 2 blocks the action, and whatever your script wrote to stderr becomes the reason Claude sees. Everything else is a non-blocking error. That is close to the whole interface, and the quickstart guide covers the rest.

That matters more than it sounds. A gate that merely warns is not a gate, because an agent working through a long task will read the warning, acknowledge it, and carry on. A gate that exits 2 removes the choice. The discipline is to decide, for each check you care about, whether you actually want the work stopped or only annotated, and then to pick the exit code that matches.

The hooks reference lists dozens of events, which is daunting until you notice they fall into three cadences: once per session, once per turn, and once per tool call. A website repository needs one from each.

Gate one: never let the build break quietly

The single highest-value hook on a website repository runs the typecheck and the production build on the Stop event, when Claude finishes responding. It is the cheapest possible answer to the question that ends every agent session: is this actually green? A session that touched fourteen files and reported success is not evidence. A build that compiled is.

On this site the gate is a single command, and it has caught real defects that reading the diff did not. Nine invented icon keys in one batch of posts, because the data file validates them at build time and nothing earlier does. A missing entry in a lookup table that would have crashed eighty-eight city pages at request time. Both would have reached production on the strength of a confident summary. Neither survived the build. The companion piece on verifying what the agent built goes through the rest of that list.

Gate two: block the edit you would never approve

PreToolUse fires before a tool call and can refuse it. The documented pattern is a matcher that narrows to a tool, an optional condition that narrows further, and a script that exits 2 with a reason. On a website the list of things worth refusing is short and stable: writes to the environment file, writes to anything generated, and any command that pushes before the build has run.

The temptation is to write this as a permission rule instead, and for some of it you should: a deny rule in your settings file is simpler and needs no script. Reach for a hook when the decision depends on content rather than on the path, which is exactly the case for secrets. A path rule cannot tell you that the string about to be written into a component is a live API key. A hook that greps the proposed content can.

Gate three: tell the agent what it cannot know

The most underused field in the whole system is additionalContext on PostToolUse. It takes a string, wraps it as a note, and drops it next to the tool result so Claude reads it on the next request. It is not a block. It is a correction delivered at the one moment the agent is still holding the relevant thought.

Ours fires when a file under the image directory is written and says one thing: the optimiser caches by source path, not by contents, so an in-place swap serves the old file until the cache directory is cleared. That is documented behaviour of Next.js image optimisation, and it is invisible from the diff, invisible from the build, and invisible from a screenshot taken too early. It cost us two rounds of confusion before the hook existed. It has cost nothing since.

Every repository has three or four facts like that: true, consequential, and not derivable from the code. They belong in a hook rather than in your project instructions, because a note that fires on the relevant edit lands better than a line in a file the agent read forty minutes ago. The piece on writing a CLAUDE.md that changes decisions covers where the line between the two falls.

Hooks are not continuous integration

A hook runs on your machine, in your session, under your settings. It protects the work in progress. It does not protect the branch, because a colleague without your settings file gets none of it, and neither does anything that reaches the repository another way. For that you still want a workflow in CI running the same commands on a clean checkout.

The useful way to hold both is that the hook is a fast local gate tuned for the agent loop, and CI is the slow authoritative gate tuned for the branch. Run the same script in both so there is one definition of green. When they disagree, the hook is wrong.

Start with one

Three gates is where this ends, not where it starts. Add the Stop hook that runs your build, work with it for a week, and see what still gets through. The second and third hooks should be written against defects you have actually had, because a gate guarding a failure that never happens is a tax on every session for nothing. On a site like ours the ordering was obvious in hindsight: the build gate paid for itself the first day, the image-cache note the first week, and the secret gate has never once fired, which is the correct amount for that one.

If you have not set up the repository yet, the build guide is the place to start, and the skills piece covers the other half of the configuration. We do this on client work as part of a custom build, and the gates come with the handover.