Claude Code hooks, explained: what they are and what you can build

The idea in one paragraph

You tell the agent: when this happens, run this command. The agent runs it and hands it a short description of the event. The command can just record it (to send a notification, for example), or, for some events, it can send an answer back that the agent uses.

Moments you can hook

Exact event names and settings differ between agents and versions, so check each agent's own documentation before writing your own.

• A session starts or ends, or you send a prompt.
• A tool is about to run, or has just run.
• The agent asks for permission to do something.
• The agent finishes its turn (a Stop event).

Where they live

In a settings file: for Claude Code that is ~/.claude/settings.json, for Codex ~/.codex/hooks.json, and for Cursor ~/.cursor/hooks.json. Editing these files by hand is fine, and it is also how a tool like Herdbell connects.

How Herdbell uses them

1. On connect, Herdbell backs up the file, then adds its own small command for the events it needs.
2. For most events it only listens, so it can show what the agent is doing.
3. For a permission request it waits for your answer and returns it, so Allow and Deny take effect. For end of turn it can hold the agent open so your reply goes back into the same chat.
4. If you do not answer in time, it lets go, and the agent falls back to its own prompt. Disconnecting removes only Herdbell's hooks.

Common questions