---
title: "Claude Code hooks: what they are, how to set up | Bombos"
description: "Claude Code hooks run handlers at lifecycle events such as tool calls, with blocking PreToolUse hooks enforcing checks that CLAUDE.md cannot guarantee."
image: "https://bombos.ai/assets/og-en-v2.png"
---

# What are Claude Code hooks and how do I set them up?

Short answer

Hooks are handlers Claude Code runs automatically at fixed moments in a session: before a tool call (PreToolUse), after it (PostToolUse), when a prompt is submitted, when Claude stops, and more. You configure them in a settings.json file. Unlike CLAUDE.md, which Claude reads as advice, a PreToolUse hook that exits with code 2 actually blocks the action.

*Piet Baudoin · published November 16, 2026 · November 16, 2026*

## Hooks in one table

A hook ties a handler to an event in the Claude Code lifecycle. The most used events:

| Event | When it fires | Typical use |
| --- | --- | --- |
| `SessionStart` | A session begins or resumes | Load extra context, print the current branch |
| `UserPromptSubmit` | You send a prompt | Add context, log prompts, reject certain requests |
| `PreToolUse` | Before a tool runs | Block dangerous commands, protect files |
| `PostToolUse` | After a tool succeeded | Run a formatter or linter on edited files |
| `PermissionRequest` | A permission dialog would appear | Auto-approve or deny known cases |
| `Notification` | Claude needs your attention | Desktop or phone notification |
| `Stop` | Claude is about to finish its turn | Ask for another turn when a check fails |
| `PreCompact` / `PostCompact` | Around context compaction | Save notes before the window is compressed |
| `InstructionsLoaded` | A CLAUDE.md or rules file loads | Audit which instructions are in play |
| `SessionEnd` | The session ends | Clean up, write a summary |

There are more, including `PostToolUseFailure` and `SubagentStart` and `SubagentStop`.

## Set one up

1.  **Pick the file.** `.claude/settings.json` in the repo for the team, `~/.claude/settings.json` for yourself, `.claude/settings.local.json` for local overrides. IT can set hooks in managed policy, and plugins and skills can carry their own.
2.  **Write the handler.** Usually a script that reads JSON from stdin. For a PreToolUse event that JSON includes `tool_name` and `tool_input`, for example the Bash command about to run.
3.  **Register it.** Under the event name, add a matcher for the tool and the handler:

```
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PROJECT_DIR}\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}
```

The script itself can be a few lines. This one blocks any Bash command that contains `rm -rf` (it needs `jq`, and `chmod +x` on macOS and Linux):

```
#!/bin/bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -q 'rm -rf'; then
  echo "Blocked: rm -rf is not allowed in this repo" >&2
  exit 2
fi
exit 0
```

4.  **Decide with the exit code.** Exit 0 means fine. Exit 2 is a blocking error: on PreToolUse the tool call does not happen, and what the script wrote to stderr goes back to Claude so it can adjust. Other codes are non-blocking errors. For finer control, exit 0 and print JSON with `hookSpecificOutput.permissionDecision` set to `allow`, `deny` or `ask`, and a `permissionDecisionReason`. A fourth value, `defer`, only works in non-interactive `-p` runs.
5.  **Check it.** Run `/hooks` to see what is active. Then ask Claude to run a harmless command, which should go through, and one with `rm -rf`, which should come back blocked with your message.

A matcher can cover several tools at once, such as `Edit|Write` for every file change.

## The misunderstanding: “I put it in CLAUDE.md, so it is a rule”

CLAUDE.md is context. Claude reads it and usually follows it, but under pressure, in a long session or after compaction, a line like “never edit the migrations folder” can lose out. The Claude Code memory docs say it directly: instructions are context, not enforcement, and to block something you use a PreToolUse hook. The split is simple:

-   **CLAUDE.md** for how you want things done: style, architecture, which commands to use.
-   **Hooks** for what must or must not happen every time: no force push, no edits to secrets, formatter after every write.

## What this means for a team

A hook in a committed `.claude/settings.json` is one of the few things in Claude Code that behaves the same for every developer, because it is code that runs, not text that is interpreted. That makes hooks the right place for the team’s hard rules. They do have limits: a hook knows only the event it receives and what its script can look up. It does not know what the team decided last week unless someone wrote that into the script. And hooks are configured per tool: Cursor can import supported Claude Code hooks when third-party hooks are enabled, though not every event carries over, and ChatGPT does not run them at all. See [how Claude Code memory works](https://bombos.ai/en/questions/claude-code/claude-code-memory/) and [how plugins bundle hooks](https://bombos.ai/en/questions/claude-code/claude-code-plugins-memory/).

## Where Bombos fits

Hooks enforce rules someone already wrote down. Bombos is a plugin that gives Claude Code and the team’s other AI tools a shared memory where those rules come from: what the team learned, what was decided in mail and documents, and the rules agents have ready for the next question, traceable to their source. One developer can try it on their own agents first.

## Related questions

Where do I put a hook so the whole team gets it?

In .claude/settings.json in the repo, and commit it. Hooks in ~/.claude/settings.json apply only to you, and .claude/settings.local.json is for local overrides.

How do I see which hooks are active?

Type /hooks in Claude Code. It lists the configured hooks from every source, including plugins and managed policy.

What does exit code 2 do on a Stop hook?

It prevents Claude from stopping and continues the conversation. That is useful to send Claude back when a check such as the test suite fails. It does not guarantee the tests pass, and the docs describe a limit on how often a Stop hook can continue.

Can a hook be something other than a shell command?

Yes. The handler types are command, http, prompt, agent (experimental) and mcp\_tool.

Can a plugin ship hooks?

Yes. A plugin can include hooks in hooks/hooks.json, which is how many plugins add behavior at session start or around tool calls.

## Sources

1.  [Claude Code docs: Hooks reference](https://code.claude.com/docs/en/hooks)
2.  [Claude Code docs: How Claude remembers your project](https://code.claude.com/docs/en/memory)
3.  [Claude Code docs: Plugins](https://code.claude.com/docs/en/plugins)
4.  [Cursor docs: Third-party hooks](https://cursor.com/docs/reference/third-party-hooks)

## What does your AI forget?

1.  01You tell us which AI you use and where it keeps starting over.
2.  02We show what a shared memory changes there, on your own examples.
3.  03You keep the plan, with or without Bombos.

![Piet Baudoin](https://bombos.ai/assets/team/piet-klein.jpg)

**Piet Baudoin**You talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe

## More questions about Claude Code

-   [What are agent teams in Claude Code and how do you turn them on?](https://bombos.ai/en/questions/claude-code/claude-code-agent-teams/)
-   [What are subagents in Claude Code and when should you use them?](https://bombos.ai/en/questions/claude-code/claude-code-subagents/)
-   [How do I use Claude Code in VS Code and JetBrains?](https://bombos.ai/en/questions/claude-code/claude-code-in-vs-code-and-jetbrains/)
-   [What is Claude Code Remote Control and how do I use it?](https://bombos.ai/en/questions/claude-code/claude-code-remote-control/)
-   [What is the Claude Code SDK, now the Claude Agent SDK?](https://bombos.ai/en/questions/claude-code/claude-code-sdk/)
-   [Does Claude Code have memory across sessions?](https://bombos.ai/en/questions/claude-code/claude-code-memory/)
-   [What does plan mode do in Claude Code and how do you turn it on?](https://bombos.ai/en/questions/claude-code/claude-code-plan-mode/)
-   [How do Claude Code plugins work, and can a plugin add shared memory?](https://bombos.ai/en/questions/claude-code/claude-code-plugins-memory/)

[All questions about Claude Code →](https://bombos.ai/en/questions/claude-code/)


---

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","url":"https://bombos.ai/","logo":"https://bombos.ai/assets/bombos-bee.png","description":"Bombos is the memory layer under every AI your team uses. One shared memory for Claude, ChatGPT, Copilot, Cursor and your own agents, that learns how you work.","sameAs":["https://www.linkedin.com/company/bombos-ai","https://www.youtube.com/@truebombos","https://www.instagram.com/truebombos/","https://bsky.app/profile/bombostrue.bsky.social","https://www.threads.com/@truebombos","https://mastodon.social/@Bombos","https://www.tiktok.com/@truebombos","https://t.me/truebombos","https://www.pinterest.com/truebombos/","https://github.com/bombos-ai","https://linktr.ee/bombos.ai","https://bombosai.substack.com","https://hashnode.com/@bombosai","https://hackernoon.com/u/bombos","https://dev.to/bombos"],"email":"info@bombos.ai","areaServed":["NL","Europe"],"knowsLanguage":["nl","en"],"contactPoint":{"@type":"ContactPoint","email":"info@bombos.ai","contactType":"sales","url":"https://bombos.ai/en/contact/","availableLanguage":["nl","en"]}},{"@type":"WebSite","@id":"https://bombos.ai/#website","name":"Bombos","url":"https://bombos.ai/","inLanguage":["nl-NL","en"],"publisher":{"@id":"https://bombos.ai/#organization"}}]}

{"@context":"https://schema.org","@type":"Article","headline":"What are Claude Code hooks and how do I set them up?","description":"Claude Code hooks run handlers at lifecycle events such as tool calls, with blocking PreToolUse hooks enforcing checks that CLAUDE.md cannot guarantee.","abstract":"Hooks are handlers Claude Code runs automatically at fixed moments in a session: before a tool call (PreToolUse), after it (PostToolUse), when a prompt is submitted, when Claude stops, and more. You configure them in a settings.json file. Unlike CLAUDE.md, which Claude reads as advice, a PreToolUse hook that exits with code 2 actually blocks the action.","datePublished":"2026-11-16T00:00:00.000Z","dateModified":"2026-11-16T00:00:00.000Z","author":{"@type":"Person","name":"Piet Baudoin"},"publisher":{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","logo":{"@type":"ImageObject","url":"https://bombos.ai/assets/bombos-bee.png"}},"image":"https://bombos.ai/assets/og-en-v2.png","mainEntityOfPage":"https://bombos.ai/en/questions/claude-code/claude-code-hooks/","inLanguage":"en-US","isPartOf":{"@type":"CollectionPage","name":"Claude Code","url":"https://bombos.ai/en/questions/claude-code/"},"citation":[{"@type":"CreativeWork","name":"Claude Code docs: Hooks reference","url":"https://code.claude.com/docs/en/hooks"},{"@type":"CreativeWork","name":"Claude Code docs: How Claude remembers your project","url":"https://code.claude.com/docs/en/memory"},{"@type":"CreativeWork","name":"Claude Code docs: Plugins","url":"https://code.claude.com/docs/en/plugins"},{"@type":"CreativeWork","name":"Cursor docs: Third-party hooks","url":"https://cursor.com/docs/reference/third-party-hooks"}]}

{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Bombos","item":"https://bombos.ai/en/"},{"@type":"ListItem","position":2,"name":"Questions","item":"https://bombos.ai/en/questions/"},{"@type":"ListItem","position":3,"name":"Claude Code","item":"https://bombos.ai/en/questions/claude-code/"},{"@type":"ListItem","position":4,"name":"What are Claude Code hooks and how do I set them up?","item":"https://bombos.ai/en/questions/claude-code/claude-code-hooks/"}]}

{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Where do I put a hook so the whole team gets it?","acceptedAnswer":{"@type":"Answer","text":"In .claude/settings.json in the repo, and commit it. Hooks in ~/.claude/settings.json apply only to you, and .claude/settings.local.json is for local overrides."}},{"@type":"Question","name":"How do I see which hooks are active?","acceptedAnswer":{"@type":"Answer","text":"Type /hooks in Claude Code. It lists the configured hooks from every source, including plugins and managed policy."}},{"@type":"Question","name":"What does exit code 2 do on a Stop hook?","acceptedAnswer":{"@type":"Answer","text":"It prevents Claude from stopping and continues the conversation. That is useful to send Claude back when a check such as the test suite fails. It does not guarantee the tests pass, and the docs describe a limit on how often a Stop hook can continue."}},{"@type":"Question","name":"Can a hook be something other than a shell command?","acceptedAnswer":{"@type":"Answer","text":"Yes. The handler types are command, http, prompt, agent (experimental) and mcp_tool."}},{"@type":"Question","name":"Can a plugin ship hooks?","acceptedAnswer":{"@type":"Answer","text":"Yes. A plugin can include hooks in hooks/hooks.json, which is how many plugins add behavior at session start or around tool calls."}}]}
```
