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.

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
  1. 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.
  2. 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 and how plugins bundle hooks.

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
  2. Claude Code docs: How Claude remembers your project
  3. Claude Code docs: Plugins
  4. Cursor docs: Third-party hooks
The first half hour · free

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
Piet BaudoinYou talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe
We reply the same working day.