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 to open the hooks browser. You’ll see a list of all available hook events, with a count next to each event that has hooks configured. Select Notification to confirm your new hook appears in the list. Selecting the hook shows its details: the event, matcher, type, source file, and command.
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.
The /hooks menu is read-only. To add, modify, or remove hooks, edit your settings JSON directly or ask Claude to make the change.

​
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 when each notification type fires for the exact timing. Each tab below uses the platform’s native notification command. Add this to ~/.claude/settings.json:
osascript routes notifications through the built-in Script Editor app. If Script Editor doesn’t have notification permission, the command fails silently, and macOS won’t prompt you to grant it. Run this in Terminal once to make Script Editor appear in your notification settings:
Nothing will appear yet. Open System Settings > Notifications, find Script Editor in the list, and turn on Allow Notifications. Run the command again to confirm the test notification appears.