Claude Code Hooks, Explained: Automating What Happens Around the Agent

If you've searched "claude code hooks" or "how to use claude code hooks," you've probably run into the same confusion people hit with skills and subagents: a feature that sounds like it needs an architecture diagram, when the real thing is one specific idea. A hook is a command the harness runs automatically at a fixed point in the agent's loop. Not a suggestion left in a prompt, not something the model does if it feels like it — a command that runs, every time, whether the model cooperates or not. That distinction is the whole point.

The distinction that matters: enforcement, not memory

Ask an agent to "always run the linter after editing a file" and most of the time it will. Then, on a long turn, or three tool calls deep into something else, it won't — not out of malice, just because an instruction sitting in context is a request the model can deprioritize. It's competing with everything else you've told it in that conversation.

A hook doesn't compete with anything. It isn't part of the model's context at all. It's a rule the harness enforces at the infrastructure level: when this event happens, run this command, no exceptions. You're not hoping the agent remembers — you've made remembering unnecessary.

This is why hooks show up in the same conversations as "coding agent guardrails" and "ai coding agent automation": they're the answer to a specific complaint, that instructions in plain language are optional, and some things shouldn't be.

Where hooks fire

Hooks attach to specific points in an agent's turn, and each point suits a different job.

Before a tool call. Stop something before it happens — block an edit to a file you've marked off-limits, refuse a command matching a pattern you don't want run. The hook runs, and it can say no.

After a tool call. React to something that already happened — run a formatter right after a file edit, kick off a type check, log what changed. The action already took place; the hook responds to it.

When a turn or session ends. Wrap-up work — a final validation pass, a summary write, anything that only makes sense once the agent is actually done rather than mid-edit.

On a notification. You get told something, rather than the agent being told to do something — a permission request needs your attention, a long-running turn has finished, the harness wants a human back in the loop.

The exact mechanics of how each point is configured vary by setup and version, so treat this as the shape of the idea rather than a literal spec. What stays constant is the principle: pick the point in the loop where the thing you care about actually happens, and attach the hook there instead of wording an instruction carefully enough to cover it.

The three things people actually use hooks for

Strip away the theory and almost every real hook falls into one of three buckets:

Guardrails. Block an edit to a protected path — a production config, a secrets file, a generated directory that shouldn't be hand-edited. Same instinct as checking what an agent can touch before it writes to real files, just enforced automatically instead of relying on review to catch it.

Automation. Run the formatter, the linter, or the typechecker after every edit, without asking. The agent doesn't need to remember and you don't need to ask — it just happens, the way a pre-commit hook runs whether or not you thought to run it yourself.

Notification. Ping you when a long turn finishes, or when the agent needs a decision only you can make. Sounds minor until you're not staring at the terminal the whole time — which is most of the time, if the agent is doing real work.

Hook vs. a line in CLAUDE.md vs. a skill

This is the same "why not just ask the agent?" question that comes up around skills, and it's worth answering directly.

A line in CLAUDE.md is a standing instruction, always in context — the agent sees it every time, but still applies it through judgment, not as a rule it's forced through. A skill is instructions loaded on demand for a specific task, matched by relevance, good for teaching the agent how to do something well. Neither can guarantee an action happens; both depend on the model reading, understanding, and choosing to follow them.

A hook sidesteps all of that. It doesn't ask the model to do the right thing — it makes the right thing happen regardless of what the model decides. If "never let the agent touch this file" is a requirement, not a preference, that belongs in a hook, not a paragraph the model has to keep re-reading correctly.

Where hooks bite you

None of this is free, and it's worth naming the failure modes instead of only the upside.

A slow hook on a frequent event makes every action drag. If your after-every-edit hook takes three seconds and you're editing constantly, that adds up fast — easy to not notice until the whole session feels sluggish.

A hook that fails silently is worse than no hook at all. If a formatter hook has been quietly erroring out for a week, you've been assuming a guarantee that stopped being true, which is worse than never having had the guarantee.

A blocking hook that misfires stops work you actually needed done. A guardrail that's slightly too broad — blocking an entire directory when you meant one file — doesn't fail loudly, it just refuses, and now you're debugging why the agent "won't" do something instead of getting the thing done.

The fix for all three is the same: keep hooks narrow, keep them fast, and check on them occasionally instead of assuming a rule you wrote once is still doing what you think.

The meshcode angle

meshcode is a native desktop app for macOS and Windows built around a multi-pane agent workspace — each pane is its own agent session, and panes run in parallel, so you're often watching several agents work at once rather than one conversation at a time. meshcode drives your existing Claude Code and Codex subscriptions directly, so hooks you've already configured carry over and keep firing — you don't rebuild them to use meshcode, they just keep working.

Notification hooks matter more once you're running several panes at once than in a single conversation. With one agent, you're already looking at it. With several running in parallel, you can't watch all of them at once, and a pane finishing quietly in the background is easy to miss. A hook that tells you the moment a pane's turn is done is how parallel work stops going unnoticed.

meshcode also runs its own metered mesh models, billed pay-as-you-go with no monthly fee, alongside whatever provider each pane is already connected to.

Stop missing finished work: meshcode is free to start — download it and let a notification hook tell you the moment a pane is done.

The takeaway

A hook is a command the harness runs at a fixed point in the agent's loop — before a tool call, after one, at the end of a turn, or on a notification — whether the model remembers to cooperate or not. That's the difference between a hook and an instruction: an instruction is a request the model can drop, a hook is enforcement. Use them for guardrails you actually need enforced, automation you don't want to keep asking for, and notifications that keep you from missing work that finished without you watching. Keep them narrow and fast, and check occasionally that they're still doing what you think. Running several agent panes in parallel instead of one conversation at a time is exactly where a notification hook earns its keep.

FAQ

How do you actually use Claude Code hooks? Define them in your settings file: pick the event to attach to (before a tool call, after one, at turn or session end, on a notification), optionally scope it to specific tools with a matcher, and give it a command. That command is anything you'd run by hand — a lint script, a formatter, a one-liner — the hook just makes it happen automatically.

How do you get notified when a Claude Code turn finishes? Attach a hook to the notification or turn-end event and give it a command that actually alerts you — a system notification, a sound, a message to yourself. It matters most once you're not staring at one conversation the whole time — meshcode's multi-pane workspace is a common reason to want one, since a pane finishing quietly in the background is easy to miss.

Why use a hook instead of just telling the agent in CLAUDE.md? Beyond enforcement, there's a cost difference: a CLAUDE.md line gets sent to the model every turn, forever, whether relevant or not. A hook isn't part of what the model reads at all — it lives in the harness config and runs regardless of context, so it costs nothing in tokens no matter how many you have.

Can a hook actually block the agent from doing something? Yes — a before-hook can stop the action before it happens, and the reason typically gets reported back so the agent can try something else instead of failing silently. That's different from an instruction the agent can quietly ignore: it can attempt the blocked action again, but the hook stops the side effect every time. A block that fires on requests you wanted allowed is a sign to loosen the matcher, not something the agent works around on its own.

👉 Download meshcode — Mac, Windows