What is a Claude Code hook and how do I use them?

In today's article we're going to take a look at a lesser mentioned aspect of a good Claude Code setup: your hooks. We did some work, as an experiment, to see how we could get Claude thinking about how it thinks - that project was called metacog. But there are many great hooks, immediately useful and simple to install - here are some of the best and most impactful for your day to day.

What hooks actually are

Hooks are how you tell Claude Code to run a little script of yours at specific moments during a session.

Think of it like a smart-home rule. When the front door opens after midnight, turn the hall light on. When Claude edits a file, run my formatter. When Claude tries to delete something destructive, stop it first and check with me. The "when" is the hook event. The "do this" is whatever shell command you put in the config.

There are about twenty different moments where you can hook in. For everyday use, four of them cover almost everything:

• When you send a message. Useful for naming sessions automatically, or for catching prompts you don't actually want to send.
• Before any tool runs (any file edit, terminal command, web fetch, etc.). Useful for blocking things you don't want Claude to do at all.
• After a tool runs. Useful for running formatters, tests, or anything that wants to react to what Claude just did.
• When Claude finishes a turn. Useful for logging cost, posting notifications, anything that should happen at the end.

The hook itself is just a shell command, an HTTP endpoint, or another LLM call. You put it in a JSON file (~/.claude/settings.json for things you want everywhere, .claude/settings.json in a project folder for things you want shared with your team) and Claude Code runs it for you at the right moment. No code-side changes needed.

The good ones stay silent unless they have something to say.

Hooks worth installing for day-to-day work

Here are the ones I'd actually point a colleague at, in rough order of "how much pain they save you."

Keep your code style consistent, automatically

Every time Claude edits or writes a file, your project's formatter runs - Prettier, Black, rustfmt, gofmt, whatever fits your stack. The AI-generated code instantly matches your project style guide, which means no more "this looks fine but the indent is wrong" review nits, no more pre-commit hook complaining at you.

This is far and away the most common hook in the wild. If you only install one custom hook, install this one. The whole setup is about ten lines of config.

Stop the dangerous stuff before it runs

The hook I install on every new machine. Catches rm -rf on directories I care about, git push --force to main or master, edits to anything in .secrets/ or .env, curl-pipe-to-shell, that sort of thing.

When the hook spots one of those, it tells Claude to stop and explains why. Claude sees the reason and doesn't just retry the same thing. It's a small amount of work to set up and it's saved me from at least one panicky git reflog already.

Run your tests automatically

If your test suite is fast enough (say, under thirty seconds for the relevant subset), wire it in. Every time Claude changes a file, the related tests run and Claude sees the output back in its context. Most test runners have a "test only what relates to these files" mode (vitest related, jest --findRelatedTests, pytest --picked) which is the only way this stays usable on a real codebase.

The pay-off is the kind of fast feedback loop you'd otherwise have to chase by hand. Claude makes a change, the test fails, Claude notices and tries again - all in the same turn, while you're still reading the explanation.

Track what your sessions are costing

If you're on a paid Claude Code plan, a one-line hook logging token spend per turn to a daily file is a sanity check that's saved me from "wait, why is this month's bill double last month's" more than once. Crude, but it works. Once a week you can tail the log and see what's actually been expensive.

Auto-name your conversations

Easy quality-of-life win. The hook reads your first prompt, picks a short title from it, and Claude Code shows that in your session history instead of "untitled-2026-05-20". Six months in, when you've got eighty conversations to scroll through, "Fix auth bug in cart" beats a date stamp every time.

Get notified when long jobs finish

Wire the "Claude is done" hook to a desktop notification, a Slack message, a phone alert, whatever you've got. Useful if you're letting Claude run a long task in the background while you do something else.

Metacog - for when Claude doesn't realise it's stuck

This is the one we built. The problem it solves: AI coding agents can't feel when they're going in circles. They'll retry the same broken fix five times because they see each error but not the pattern of repeated failure. They'll read the same file three times because context compaction wiped their memory. They'll chase a rabbit hole and forget what they were originally fixing.

Metacog is a pair of hooks that watches for those patterns and quietly tells Claude when it spots one. When everything's fine, you don't notice it's there. When something's off, a short signal appears in Claude's context - and the agent's own reasoning gets to decide what to do about it. If it keeps failing, the signals get more insistent until Claude has to stop and rethink.

The interesting bit: when problems resolve, the system writes down what changed and reuses that rule in future sessions. Most memory systems forget rules that work (no failures = nothing to remember). Metacog inverts that - if the rule was active and the failure didn't happen, that counts as evidence the rule's doing its job.

One command to install:

npx @houtini/metacog --install

Full write-up at github.com/houtini-ai/metacog if you want the deeper version.

Where to find more hooks

A few places worth bookmarking:

• [Anthropic's official hooks reference](https://code.claude.com/docs/en/hooks) is the source of truth for what events exist and what they can do. It's reference material rather than tutorial-style writing, but if you need to know exactly when a particular event fires or what JSON shape it gives you, this is where to look.
• [karanb192/claude-code-hooks](https://github.com/karanb192/claude-code-hooks) is a community-maintained collection of copy-and-paste hooks. Browse it, find one that does something useful, paste into your settings, tweak. Same energy as people sharing their dotfiles.
• [@houtini on npm](https://www.npmjs.com/org/houtini) for the packages we maintain (metacog plus the rest of our MCP servers). One-command installs for the ones that have CLI installers.
• Your favourite npm and GitHub search. Search for claude code hook and you'll find the community work in both places. Most of the useful stuff is open source.

A quick warning before you go installing anything: hooks have full shell access on your machine. They run whatever command you put in settings.json. Earlier this year a set of malicious npm packages were caught backdooring Claude Code sessions by hijacking a hook event - five packages, typosquatted on real names, hidden binaries that fired on every session start.

Read the actual hook command before you paste it into settings. Pin the version of any npm package you install (@houtini/metacog@0.5.2, not @houtini/metacog). Treat hooks the same way you'd treat anything else that runs as you on your machine.

If you only do one thing today

Install metacog. The silent-by-default, gets-stronger-when-it-works pattern is the kind of thing you forget is even there until it saves you from a thirty-minute debugging loop.

If you've already got it, or it's not your thing: write the auto-formatter hook. Ten minutes of setup, eliminates an entire category of "Claude's code doesn't match our style" nits forever.

Either way, the point of hooks is the same. Give Claude Code a few automatic reflexes for the things you'd otherwise do manually, then forget they exist until they earn their keep.