A hook connects a session event to a command. We will build a notification hook, then a hook that formats an edited Python file. Along the way, we will read the configuration and inspect the event data.
Before connecting anything to the agent, run the command yourself. On a Linux desktop, notify dash send is a standard command that pops up a notification. On WSL, ask the agent to write a small script for this. It can run PowerShell from inside WSL and show a notification window in Windows. On a Mac, the agent can write one too. Whatever the command is, first check that it works on its own, outside the hook.
Our first hook will start that command when Claude Code produces a permission notification. It will alert us while another window is in front.
Here is the whole configuration, in the file dot claude slash settings dot JSON. The outer hooks entry contains our hook configuration. Notification is the event. It tells the harness which point in the session we care about.
A matcher selects the occurrences we want. Here we select permission notifications, with the matcher "permission prompt". We do not need to react to every kind of notification just because it shares the same event.
The handler has "type: command", followed by the command to execute. This is the command we tested by hand. Read the entry as three decisions. The event says when to consider running, the matcher says which occurrences match, and the handler says what to run.
The slash hooks menu lets us inspect configured hooks and their events. Check that this notification hook is loaded. Then trigger a harmless action that needs permission in this session's settings.
With another window in front, the desktop notification tells us that the session needs attention. The original permission prompt is still waiting. This completes the first example. An event matched, the harness started the command, and we saw its effect.
Our second example is a hook that formats a Python file right after the agent edits it. The code the agent writes then keeps the project's layout, and nobody has to run the formatter by hand. For that, the hook must know which file was edited. The harness tells it. It sends a JSON object that describes the event to the program's standard input. The object names the event, the working directory, the tool, and the tool's input. We are showing only the fields needed for this example.
The file path inside the tool input tells our handler which file was edited. Different events have their own specific fields. Find those in the documentation, or simply ask the agent about them.
Now we register the formatting hook. It uses the same settings structure as the notification example. The event is PostToolUse, which happens after a tool has succeeded. The matcher selects the Edit and Write tools.
The command starts the project's Python interpreter with our handler script. Both paths are quoted and anchored at the project directory. The variable Claude_Project_Dir holds that directory, and the quotes keep each path together even if it contains a space. In the settings file, those inner quotation marks are escaped with backslashes.
The matcher lets through only Edit and Write events. Our script then reads the file path and checks whether it is a Python file. We only want to format Python files.
An edit to the Python file reaches the formatter. An edit to the readme passes the matcher, and our script ignores it. Agents often change files with a Bash command instead of the Edit tool, for example with sed or a small script. That change does not match Edit or Write, so this hook never runs. To cover it, we could also match the Bash tool, and have the script check whether the command modified any Python files.
There are several places where a settings file exists, and you can register your hook in any of them. User settings apply across your projects. Project settings travel with the repository when committed. Local project settings let you keep an adjustment on your machine. Choose the location according to who should use the hook.
Sharing the configuration is only part of sharing the hook. The script it starts and the tools it needs must also be available. Use a project-relative location for the handler, and document how its environment is installed. A path into your personal home directory will not work on your partner's machine.
A hook runs code with the access of the account running the agent. Read that code before enabling it. Keep event text as data, pass paths safely, and test a path containing spaces. Also test a file the handler should ignore. These checks tell us whether a small automation behaves as intended before it runs repeatedly without our attention.
To recap: A command hook combines a small program with a trigger. Start with a command that works, connect it to the intended event, and test the whole path. That gives you automation that runs at the right moment, without you starting it by hand.
With a notification hook in place, you can step away and make yourself a coffee while the agent works. If it needs you, it will let you know. Sadly, no hook event brings the coffee back to your desk. See you in the next video.