How Hooks Make AI Coding Agents Actually Follow Your Rules
Hooks let Claude Code, Codex, and other AI coding agents enforce rules deterministically. Here's how they work and when to use them.
What are hooks in AI coding agents?
Hooks are scripts that run automatically when an AI coding agent hits a specific event, like right before it reads a file, right after it edits one, or the moment it decides a conversation is finished. Instead of asking the agent nicely to follow a rule, a hook forces an outcome by running deterministic code and returning an exit status that tells the agent whether it can continue, needs to stop, or has to go back and fix something. Claude Code, Codex, and other agent harnesses all support this same primitive, even though the configuration details differ.
TL;DR
- Hooks are guarantees, not guidance, unlike rules written in a CLAUDE.md or AGENTS.md file, which an LLM can still skip or misinterpret because it’s a probabilistic system.
- A stop hook can force test runs, running your full test suite the moment an agent claims it’s done and blocking completion until everything passes.
- Exit codes drive the logic, where an exit code of zero lets the agent proceed and an exit code of two blocks the action or forces the agent to keep working.
- Piling on more rules tends to backfire, and research cited in the source material found that letting an agent keep appending to its own system prompt actually hurt performance, while adding middleware-style hooks improved it on most task types.
- Hooks work across tool boundaries, meaning the underlying script can be bash, Python, or TypeScript, and the same mental model applies whether you’re using Claude Code, Codex, or another agent.
- The right move is to audit existing rules, looking for the steps an agent occasionally skips or reorders, since those are the strongest candidates for conversion into a hook.
One coffee. One working app.
You bring the idea. Remy manages the project.
Why do coding agents ignore your rules?
Large language models are probabilistic. They don’t process a written instruction the same way every single time, which means a rule buried in a system prompt or an AGENTS.md file is a strong suggestion, not an enforced constraint. This shows up constantly in real workflows: you tell the agent to run your full test suite after every implementation, and most of the time it does, but occasionally it skips a check, misses a step, or declares a task complete while part of the suite is still failing.
This gets worse as codebases grow and the number of required checks increases. The more steps you cram into a rule, the more surface area there is for the agent to miss one. And simply adding more rules to compensate doesn’t fix the underlying issue, it just spreads the agent’s attention across more competing instructions.
How do hooks solve the reliability problem?
A hook extracts a process out of the agent’s “judgment” and turns it into code that runs no matter what. The agent doesn’t get to decide whether to run the test suite when a conversation ends. A stop hook fires automatically, executes the test suite, and checks the results. If everything passes, the hook exits cleanly and the conversation ends as normal. If something fails, the hook blocks the stop, surfaces the failure output, and forces the agent to keep working until the tests are green.
That’s the core distinction between hooks and every other part of an agent’s configuration:
- Rules and skills are guidance. They shape behavior but rely on the model to remember and apply them correctly.
- Hooks are deterministic automation. They run the same way every time, independent of whether the model “remembers” to do it.
Mechanically, a hook is just a script tied to an event. The script can be written in bash, Python, TypeScript, or whatever fits your stack. When the event fires, the script runs and returns an exit code:
- Exit code zero means the check passed or the action is allowed to proceed.
- Exit code two means something is blocked or needs to be fixed, and the agent is forced to respond to that before continuing.
Other exit codes generally signal that the hook script itself broke, which is a separate debugging concern from the pass/fail logic of the check itself.
What events can trigger a hook?
Coding agents expose a menu of lifecycle events you can attach hooks to. The two most commonly used are:
- Pre-tool-use hooks, which fire right before the agent performs an action, such as reading a file. This is where you’d block access to a secrets file or a protected directory before the agent ever touches it.
- Stop hooks, which fire when the agent believes a turn or conversation is complete. This is where you enforce guarantees like “the full test suite must pass before you’re allowed to hand control back.”
- ✕a coding agent
- ✕no-code
- ✕vibe coding
- ✕a faster Cursor
The one that tells the coding agents what to build.
Beyond blocking and validation, hooks are also used for logging and observability, giving teams an audit trail of what an agent attempted and when, independent of whatever the agent reports about its own actions.
Should every rule become a hook?
No, and treating hooks as a replacement for all rules would be a mistake. Rules and skills still matter for guidance, context, and workflows that require judgment rather than a strict pass/fail check. The problem is when teams keep stacking rules on top of rules to patch reliability issues, which tends to dilute the agent’s focus rather than sharpen it.
Research referenced in the source material illustrates this directly. In one setup, a coding agent was allowed to evolve its own system prompt (its global rules) over time based on an evaluator judging its performance across tasks of varying difficulty. When the agent was left to keep appending to its own rules, performance actually got worse across the board, even though individual added rules might have helped in isolation. When the same setup instead let the agent evolve its “middleware” (hooks), performance improved on every task type except the hardest ones, where evolving hooks and rules together produced the best results.
The practical takeaway: if you notice your rules file growing every time you hit a new edge case, that’s a signal to look at what’s being added. Steps describing a fixed, checkable process (run tests, block a file path, log an action) belong in a hook. Steps describing judgment, context, or preference belong in a rule.
How do you decide which rules to convert?
The simplest audit is to look for rules that describe an “if this happens, then do this” sequence, especially ones the agent has skipped or gotten wrong before. Classic candidates include:
- Running a full validation or test suite before considering work complete.
- Blocking access to sensitive files or directories (credentials,
.envfiles, production configs). - Enforcing a specific order of operations for a multi-step workflow.
- Logging tool calls or file access for auditing purposes.
Once you’ve identified a candidate, the conversion process can be as simple as describing the guarantee you want: what event should trigger the check, what the check should verify, and what should happen on failure. From there, the mechanics are mostly boilerplate, wiring the script to the right event in your agent’s configuration (for Claude Code, this lives in a settings file where hooks are mapped to specific lifecycle events).
Is setting up hooks worth the effort?
For any team running AI coding agents past the toy-project stage, yes. The alternative is discovering, repeatedly, that an agent occasionally skips a step in a written process, and there’s no way to fully close that gap by adding more prose to a rules file. Hooks convert your most important guarantees (security boundaries, testing discipline, audit logging) from probabilistic hopes into deterministic checks. The setup cost is a one-time investment per guarantee, and it applies across agents since the concept of an event-triggered script with a pass/fail exit code is shared by Claude Code, Codex, and other harnesses.
Frequently Asked Questions
What’s the difference between a hook and a rule in an AI coding agent?
Other agents ship a demo. Remy ships an app.
Real backend. Real database. Real auth. Real plumbing. Remy has it all.
A rule is a written instruction in a file like AGENTS.md or CLAUDE.md that the model reads and tries to follow. A hook is a script tied to a specific event that runs automatically and returns a pass or fail result, making the outcome deterministic instead of dependent on the model’s interpretation.
Do hooks work the same way in Claude Code and Codex?
The underlying concept is the same across agents: scripts triggered by lifecycle events like pre-tool-use or stop, communicating back via exit codes. The configuration format differs by tool (for example, Claude Code uses a settings file to map events to scripts), so specifics need to be adapted per platform.
What happens when a hook blocks an action?
The hook script exits with a code that signals failure (an exit code of two in the examples described), and the agent receives that signal along with any output explaining what went wrong. The agent is then forced to address the issue, whether that means fixing failing tests or being denied access to a blocked file, before it can proceed.
Can adding too many hooks cause the same problems as too many rules?
The research referenced in this space suggests hooks scale better than rules because they’re deterministic rather than competing for the model’s attention, but hooks still need to be evolved thoughtfully alongside rules rather than piled on indefinitely, especially for harder, more open-ended tasks.
What’s a good first hook to set up?
A stop hook that runs your test suite whenever the agent thinks it’s finished is a common starting point, since it directly addresses one of the most frequent failure modes: an agent declaring work complete while some checks are still failing.
