Hooks: Deterministic, in Quotes

Hooks are the last thing in the .claude directory, and I have mixed feelings about them. The idea is good: a shell script that runs at a fixed point in a prompt's execution, after a tool is used, say, so you get a deterministic way to verify something or run a command. The catch is that the thing deciding to run the hook is Claude. I have had entire hooks ignored because Claude decided the hook wasn't set up correctly. So they're deterministic, in quotes. Not 100% reliable, and to me that means not deterministic. I'll show you how they work anyway, and later in the course I'll show you what I use instead.

The hook I want is simple: after Claude edits an Elixir file, run mix format on it. That's a PostToolUse hook on the Edit tool (yes, tools again; you keep seeing them for a reason). I don't use hooks much, so I ask Claude what I'm missing before it builds anything, which is a habit worth having with a frontier model: it will often tell you something you hadn't considered.

I want to create a hook that implements mix format. Every time I edit an Elixir file, I want that file to be formatted according to Elixir standards. Create that hook for me. But before you do, tell me if there's anything I'm missing or something I should think about.

It comes back with good points: format only the file that was edited, mix format will fail if the edit left broken code, and since the formatter rewrites the file after the edit, Claude may have to reread it. Its recommendation is a PostToolUse hook in .claude/settings.json that reads the file path out of the tool input, skips anything that isn't .ex or .exs, runs mix format from the project root and exits 2 on failure.

Let's go with a project-level file.

What lands is a hooks section in settings.json with a matcher for Edit, MultiEdit and Write, pointing at .claude/hooks/mix-format.sh. To prove it works I mangle the pipes in moebius.ex by hand and ask Claude to make a small edit.

I want to test that this works. So I'm going to go into moebius.ex and mess with the formatting, and then I want you to go in and add some comments to it so I can see the hook actually work.

The hook fires in the live session and the pipes come back the way the community likes them. That's the point of hooks: little shell scripts along the way. The warning stands, though. pi.dev and OpenCode have extensions that are recognized as real tools, which gets you much closer to actually deterministic, and I've had more luck with those. We'll get into the differences later.

That wraps the quick tour of skills, commands, agents and hooks. Next we build something real and I show you the skills and instructions I'd actually use. If you want a head start, my Claude Code starter template, the Claude Playbook, is on Big Machine with my skills and the patterns and practices (Gang of Four, SOLID) I still think matter when an agent is writing the code. Matt Pocock's skills repo on GitHub is worth a look too; he wrote grill-me, a paragraph-long skill that just asks you questions until a topic is exhausted. All of that said, the best skill set is your own. Make your own lightsaber, and carry it from project to project.