ENPractical hook guide
Claude Code Notification Hooks
Get a desktop alert when a Claude Code session needs your input. Start with a local notification, then narrow the events you want to hear about.
View copyable examples1. Choose your scope
Use ~/.claude/settings.json for your projects, or .claude/settings.local.json for a local setup in one project.
2. Add one example
Choose the command for your desktop OS. Merge the Notification entry into the existing hooks object.
3. Check the event
Open /hooks in Claude Code, then trigger a matching event in a small test session.
Choose a Notification matcher
| Matcher | Use it for |
|---|---|
| permission_prompt | A pending request for your permission. |
| idle_prompt | A session waiting for your input. |
| permission_prompt|idle_prompt | Either event, as in the examples below. |
Match notification types here, not tool names such as Bash. Notification delivers an alert; it does not approve a tool request. Use Stop when you specifically need an end-of-turn hook.
Claude Code notification hook examples
Choose one OS example. These commands use fixed notification text, so event messages are never inserted into shell source. If your settings already contain Notification handlers, append one handler to that array; keep existing settings and hooks.
macOS desktop notification
macOS · settings JSON
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt|idle_prompt",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"A coding session is waiting for your input.\" with title \"Claude Code\"'"
}
]
}
]
}
}Linux desktop notification
Linux · settings JSON
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt|idle_prompt",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'A coding session is waiting for your input.'"
}
]
}
]
}
}Requires notify-send and a desktop notification service. On Debian/Ubuntu, notify-send is provided by libnotify-bin. A headless server or SSH session may have no desktop to notify.
Test the command, then test Claude Code
First, run the selected command in your terminal. This tests the OS notification route before adding a Claude Code event to the test.
macOS · test in Terminal
osascript -e 'display notification "A coding session is waiting for your input." with title "Claude Code"'Linux · test in Terminal
notify-send 'Claude Code' 'A coding session is waiting for your input.'- Save the settings and open
/hooks. Confirm a Notification handler is listed. If it does not appear after a few seconds, check the JSON and restart the session. - Use a disposable project with a permission mode that asks for approval. Request a small operation requiring permission and leave the prompt unanswered briefly.
- Check for the alert. Answering immediately may finish the request before a notification is due. Record the event and version when investigating a missed alert.
- For idle alerts, let the session wait for input. Expect the Notification event’s timing, rather than an alert on every completed message.
If the notification does not appear
No alert from the terminal test
Check the OS first. On macOS, allow Script Editor in System Settings → Notifications. On Linux, check notify-send and your desktop notification service.
Terminal test works, but /hooks is empty
Confirm the file location and valid JSON. Do not paste both complete examples into one file. Check whether managed policy restricts user hooks.
The handler is listed, but the event is silent
Verify the matcher and event type. A permission answered immediately or a session that is still working may not send the notification you expect.
The same alert appears twice
Inspect user, project and plugin settings for duplicate handlers. Keep one OS command for each event you want to notify.
Configuration and event behavior checked 2026-10-13 against the official setup guide and Notification reference. Desktop notification permissions still depend on your OS.