Skip to main content
Hooks are user-defined shell commands. Claude Code runs them at specific points in its lifecycle, which gives you deterministic control: certain actions always happen rather than relying on the LLM to choose to run them. Use hooks to enforce project rules, automate repetitive tasks, and integrate Claude Code with your existing tools. For decisions that require judgment rather than deterministic rules, you can also use prompt-based hooks or agent-based hooks that use a Claude model to evaluate conditions. For other ways to extend Claude Code, see skills for giving Claude additional instructions and executable commands, subagents for running tasks in isolated contexts, and plugins for packaging extensions to share across projects.
This guide covers common use cases and how to get started. For full event schemas, JSON input/output formats, and advanced features like async hooks and MCP tool hooks, see the Hooks reference.

​
Set up your first hook

To create a hook, add a hooks block to a settings file. This walkthrough creates a desktop notification hook, so you get alerted whenever Claude is waiting for your input instead of watching the terminal.
1

Add the hook to your settings

Open ~/.claude/settings.json and add a Notification hook. If the file doesn’t exist, create it. The example below uses osascript for macOS; see Get notified when Claude needs input for Linux and Windows commands.
If your settings file already has a hooks key, add Notification as a sibling of the existing event keys rather than replacing the whole object. Each event name is a key inside the single hooks object:
You can also ask Claude to write the hook for you by describing what you want in the CLI.
2

Verify the configuration

Type /hooks at the Claude Code prompt to open the hooks browser. Your new hook appears in the list under Notification.
3

Test the hook

Press Esc to return to the CLI. Press Shift+Tab until the status bar shows ⏸ manual mode on, ask Claude to do something that requires permission, then switch away from the terminal. You should receive a desktop notification.

​
What you can automate

Hooks let you run code at key points in Claude Code’s lifecycle: format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start, and more. For the full list of hook events, see the Hooks reference. Each example includes a ready-to-use configuration block that you add to a settings file. For a production example of hooks that run a separate model review and feed findings back into the session, see how the security-guidance plugin integrates with Claude Code.

​
Get notified when Claude needs input

Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal. This hook uses the Notification event, which Claude Code fires when Claude is waiting for input or permission. See