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

> Hooks let Claude Code run your command when a tool starts, it asks permission or a turn ends. How they work, and how Herdbell uses them.

Canonical: https://herdbell.com/blog/claude-code-hooks-explained
Last updated: 2026-10-27

A hook is a small command that an agent runs at a set moment. Claude Code, Codex and Cursor all support them in some form, and they are the clean way for another program to follow what an agent is doing without signing in to anything or scraping a screen.

## 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

### Do hooks need an API key or login?
No. A hook is a local command on your Mac. Herdbell uses them so it never needs to sign in to an agent or call an AI model.

### Can a hook break my agent?
A badly written one can slow or confuse it, which is why Herdbell backs up your settings first, keeps its hooks small and lets go when you do not answer. You can disconnect it any time.

## Related
- [Herdbell: pricing](https://herdbell.com/#pricing)
- [All posts](https://herdbell.com/blog)
- [How to get notified when Claude Code finishes or needs your approval](https://herdbell.com/blog/get-notified-when-claude-code-finishes)
- [Claude Code vs Codex vs Cursor: how to monitor all of them in one place](https://herdbell.com/blog/claude-code-vs-codex-vs-cursor)