Hooks & Events

Hooks are optional automations or guardrails that run at specific moments in a Claude Code session.

Most teams do not need to learn the full hook surface area on day one. Start here if you are ready to add one small guardrail or one small feedback loop. If you are not there yet, keep using Daily Workflow and Project Setup first.

Do you need hooks yet?

You probably do not need hooks yet if:

• the team is still learning the basic session flow
• you are still revising CLAUDE.md
• nobody can clearly explain which behavior needs enforcement

You probably do need a first hook if:

• one risky action keeps repeating
• one helpful post-edit action keeps getting forgotten
• the team already agrees on the workflow and wants a lightweight way to reinforce it

The 3 hooks to learn first

Everything else is later.

Minimum useful setup

If you only want one safety hook and one feedback hook, the shape looks like this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-dangerous.sh",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-format.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

That is enough to understand the model:

• a hook listens to an event
• a matcher narrows which tool calls it applies to
• a handler does the work
• exit codes decide whether Claude continues or gets blocked

Handler types in practical order

command

Start here.

Use shell commands when the decision is local, fast, and easy to explain. Most first hooks should be command hooks.

agent

Use this later when the hook needs to inspect files, run tools, and make a richer judgment, such as a final verification pass.

http and prompt

Ignore these until you have a clear external-policy or model-judgment use case. They are real, but they are not how most teams should learn hooks.

Exit codes in human terms

For beginners, think in three words: allow, warn, block.

Try it yourself

Use this safe first exercise:

1. Create a tiny hook script that appends the edited file path to a log file.
2. Add it as a PostToolUse hook for Write|Edit|MultiEdit.
3. Make one small edit in the repo.
4. Confirm the log entry appears.

Prompt:

Help me add a harmless PostToolUse hook that logs edited file paths so I can learn the hook mechanics before I add real guardrails.

What you should see:

• Claude creates a tiny hook script
• settings.json gets one narrow PostToolUse entry
• the next edit leaves a visible breadcrumb you can inspect

That is a better first lesson than starting with a giant enforcement stack.

Common beginner mistakes

• adding several hooks before the team understands the daily workflow
• putting slow work in PreToolUse
• using a hook to enforce a rule nobody has actually agreed on
• copying advanced events because they sound powerful
• turning a convenience automation into a blocker before the team trusts it

Advanced hook events you can ignore for now

Once the basics work, these events become useful in larger setups:

There is nothing wrong with these events. They are just later-stage tools.

Practical recommendation

Adopt hooks in this order:

1. one safety hook
2. one feedback hook
3. an optional Stop verification gate
4. advanced lifecycle hooks only after the team is already comfortable with the basics