Automate actions with hooks - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. 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. { "hooks" : { "Notification" : [ { "matcher" : "" , "hooks" : [ { "type" : "command" , "command" : "osascript -e 'display notification \" Claude Code needs your attention \" with title \" Claude Code \" '" } ] } ] } } 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: { "hooks" : { "PostToolUse" : [ { "matcher" : "Edit|Write" , "hooks" : [{ "type" : "command" , "command" : "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \" $f \" " }] } ], "Notification" : [ { "matcher" : "" , "hooks" : [{ "type" : "command" , "command" : "osascript -e 'display notification \" Claude Code needs your attention \" with title \" Claude Code \" '" }] } ] } } 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 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 : macOS Linux Windows (PowerShell) { "hooks" : { "Notification" : [ { "matcher" : "" , "hooks" : [ { "type" : "command" , "command" : "osascript -e 'display notification \" Claude Code needs your attention \" with title \" Claude Code \" '" } ] } ] } } If no notification appears 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: osascript -e 'display notification "test"' 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. { "hooks" : { "Notification" : [ { "matcher" : "" , "hooks" : [ { "type" : "command" , "command" : "notify-send 'Claude Code' 'Claude Code needs your attention'" } ] } ] } } If no notification appears notify-send needs a desktop notification daemon, which headless servers, SSH sessions, and most containers don’t have.
Test the command directly first: notify-send 'Claude Code' 'test' If the command isn’t found, install the libnotify-bin package on Debian and Ubuntu, or your distribution’s equivalent. { "hooks" : { "Notification" : [ { "matcher" : "" , "hooks" : [ { "type" : "command" , "command" : "powershell.exe -Command \" [System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code') \" " } ] } ] } } If no dialog appears This command opens a dialog box rather than a notification in the corner of your screen, so the dialog can open behind your terminal window.
Test the command directly in PowerShell first. If you run Claude Code inside WSL, powershell.exe must be available on your PATH through Windows interop. The empty matcher fires on all notification types. To fire only on specific events, set it to a notification type, such as one of these: Matcher Fires when permission_prompt Claude needs you to approve a tool use or a sandboxed command’s network request , and the prompt has waited about six seconds idle_prompt Claude finished responding about 60 seconds ago and you haven’t typed since auth_success Authentication completes auth_storage_failure Your sign-in completes, but Claude Code can’t save the new credentials to its credential storage .
Fires in place of auth_success elicitation_dialog An MCP server opens an elicitation form and you haven’t typed for about six seconds elicitation_url_dialog An MCP server asks you to open a browser URL and you haven’t typed for about six seconds elicitation_complete An MCP server reports that a URL-mode elicitation is complete elicitation_response An MCP elicitation response is sent back to the server agent_needs_input A background session starts waiting on your input while agent view is open.
Also fires when a terminal session shows you an agent team teammate’s terminal setup question or auto mode’s notice about classifier request charges and you haven’t typed for about six seconds agent_completed A background session finishes or fails. Fires only while agent view is open quota_auto_resume_fired Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the model-setting exception quota_auto_resume_stale A claude.ai usage limit reset while your computer slept for more than about 30 minutes.
Claude Code waits for you to press Enter instead of continuing. After a shorter sleep it continues and fires quota_auto_resume_fired instead quota_auto_resume_disabled Claude Code ends its wait for a claude.ai usage limit without continuing your task: autoContinueAtUsageLimit turned off or the reset moved more than 24 h
The rest of this page is on the live site.