Claude Code Notifications: local hooks and permissions

The Claude Code Notifications can alert your computer when the session requires permission or attention. A hook Notification calls a local operating system command; the matcher can narrow it down to the type of alert desired. You don't need to transmit prompts or code to an external chat to know that you need to get back to the terminal. Official Notification Guide.

The decisive choice is the meaning of the notice. "We need a permit" and "Claude has finished an answer" do not mean "the project is ready for production". A useful signal indicates what attention is needed and leaves the session with the full explanation. To orient yourself among the available mechanisms find the Guide to the Claude Code Hooks.

This page uses verified sources on 9 October 2026. Commands are instructional examples, not executed in this guide. Actual delivery of a notification depends on the operating system, desktop session, and the permissions of the process that shows it.

What moment must the warning produce?

Start with an observable need: go back to the computer when Claude Code waits for a permit, or when the session is waiting for input. Notification has documented types, including permission_prompt and idle_prompt. The matcher selects the type, instead of the name of a tool. The contract and the time of each notification should be read in the reference of the current version. Notification.

If you want to report any completed responses, Stop It's a different event. It can produce many alerts when the task requires short shifts. In a delegated stream there are also moments related to the agents; before using a generic matcher it is better to know what activity should call the user.

A well-chosen warning avoids two opposite errors: noise at every small action and silence when a decision is required. The appropriate frequency is evaluated using the workflow, without inventing a percentage of productivity. If duplicate signals arrive after a test, check the client's native settings and other recorded hooks as well.

How to try a notification on macOS?

On macOS a local example uses osascript. Test the command in the terminal first, with a fixed text that does not contain customer information. The following snippet is an unexecuted instructional adaptation; it uses the AppleScript notification feature also called in the Claude Code guide. Official Quickstart.

osascript -e 'display notification "Serve una decisione nella sessione" with title "Claude Code"'

If the warning does not appear, the problem can precede any hook: notifications disabled for the involved application, concentration mode, differences between terminal and desktop application. Check the system settings for the program that actually executes the command. A test from the terminal and a test from another client may use a different context.

Avoid adding the prompt to the AppleScript with shell concatenations. In addition to the risk of quotation, the text can become visible in a banner while you share the screen. A stable title and a neutral phrase are normally sufficient. The session retains the detail and reason for the request, which you can read upon return.

Which command to use in a desktop Linux session?

The guide shows the use of notify-send for Linux. The program must be available and the process must reach the graphic environment notification service. It is not a guaranteed property of every system running Linux: servers without desktops, remote terminals, and containers can have a different context. Platform Commands.

notify-send 'Claude Code' 'Serve una decisione nella sessione'

The test must be done in the environment that will launch the hook. If you run Claude Code through a remote terminal, the command can run on the server instead of the computer where you want to receive the banner. Don't solve the problem by copying session variables indiscriminately: you could create a fragile link or expose unnecessary values.

For personal use, a local configuration to the machine prevents the colleague with another desktop from inheriting a non-existent command. For a team, document the prerequisites and leave the native command in the appropriate scope. The project can share the meaning of the warning without imposing the same system executable on everyone.

How to show a local alert in Windows?

Windows requires a command or script suitable for the session and its permissions. The following example PowerShell uses a notification via System.Windows.Forms.NotifyIcon in an interactive desktop session. It is an untested teaching proposal, not a requirement of Claude Code and not a guarantee of compatibility with every Windows environment.

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing
$notice = New-Object System.Windows.Forms.NotifyIcon
$notice.Icon = [System.Drawing.SystemIcons]::Information
$notice.Visible = $true
$notice.BalloonTipTitle = 'Claude Code'
$notice.BalloonTipText = 'Serve una decisione nella sessione'
$notice.ShowBalloonTip(3000)
Start-Sleep -Seconds 4
$notice.Dispose()

Save it to a local file as notify-claude.ps1, then try to launch it directly with PowerShell. The duration present in the code is an example choice to allow the process to maintain the icon while displaying the warning; it does not represent a performance measure. The test should be performed on the reader's computer.

The hook recording must recall the correct path of the file with separate arguments and suitable quotation. Do not suggest changing the execution policy globally to start a notification. If the business system prevents a local script, use the path authorized by the administration and document the limit. The official guide includes a PowerShell alternative to compare with the actual configuration. Notifications on Windows.

Where to register a personal notification?

A computer notification often belongs to user or local settings: executable, permissions, and desktop depend on the machine. Shared repository rules can instead describe moments that require attention. The different sources of settings and their precedence are documented by Anthropic. Settings.

This example macOS records an alert only for permission_prompt. It is a block to integrate into existing settings, not a file to copy over an already rich configuration. It was not executed in this guide.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Serve una decisione nella sessione\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

For Linux it changes the handler with the command already tried. For Windows, it calls up the local PowerShell script. Do not mix three different platform commands in the same list assuming that Claude Code chooses the right one: corresponding handlers can be called together. The choice of environment must be explicit.

How to verify event, delivery and content?

The test has three parts. First check the native command; then check the recording in /hooks; finally causes a request for permission in a test repository with synthetic data. Note if the event came to the script, if the system accepted the notification, and if the banner was visible. These steps may fail separately.

Do not declare a hook working just because the command returns a positive exit code: this proves a technical aspect, while the request is to receive a perceptible warning on the correct computer. To investigate a specific loop of the route consult Hooks debugging.

Why avoid prompts and paths in the banner?

The desktop is a visible place: screen sharing, recordings, colleagues next door, and notifications on the locked screen can make text accessible beyond the session. Do not enter information that does not serve to decide whether to return to the terminal. “Claude Code requires attention” is enough; the full name of a customer or the text of a document is not.

This criterion also reduces the problems of quotation. A message built from arbitrary data must handle quotation marks, newlines, and special characters. Fixed text avoids turning hook input into code for AppleScript, shell, or PowerShell. If projects need to be distinguished, use a non-sensitive, team-defined local label.

Information management is part of the work on AI and Data Security. The notification must not become a parallel copy of the transcript. For the same reason, Slack webhooks, emails or other automated mailings are not proposed here: the described need is solved on the computer.

Can a notice certify test and end of project?

No. Stop indicates an terminated response, while Notification reports one of the types expected from the product. A sound or banner does not certify that a build has been successful or that a revision has been made. The delivery must cite the relevant outcomes, concluded and related to the current status of the files.

If you want to receive feedback on formatters and suites, define the control with PostToolUse for formatting and testing. If you want to impose a condition before the conclusion of the answer, design one Stop hook without loop. Linking the alert to an event does not correct a vague completion condition.

In a team, the end of a subagent and the end of a task are also distinct moments. Hooks for subagent and team explains where to hook up the evidence. A “finished agent” message can be useful for coordination, as long as it is not automatically translated to “the whole work is validated”.

Two Italian situations where attention is needed

Hypothetical example, untested: a developer in Turin maintains the site of a small manufacturing company. While Claude Code prepares a change in a trial checkout, it goes on to read the specification. A notification on permission_prompt signal that a decision is required. The banner does not include the client name or the proposed command; the developer reads the detail in the session before deciding.

Hypothetical, untested example: a consultant in Florence uses a Linux laptop with a graphical desktop and a remote test server. The command notify-send works on the laptop, but not on the remote session. The evidence makes it clear that the hook runs on the server. The consultant chooses a local path for the job that requires desktop alerts or documents the absence of the banner in the remote environment. He does not attribute the problem to the matcher without checking where the command is executed.

The two scenarios show a concrete difference: the position of the session counts as much as the event. Before adding an external service, check if the alert can be produced at the place where you work and if you really need a delivery out of the desktop.

How to choose a frequency that remains useful?

Start with just one attention event. After the test he observes if he alerts at a usable time, if he arrives twice and if he includes what is needed. Don't add an alert to every tool call for security: a noisy stream can lose its call function, even if technically all calls work.

When the banner interrupts too often

Check what type of Notification produces it and narrow the matcher to the actual need. Then check if the client already shows an equivalent warning. Keep the permission request recognizable and separate any end-of-response signals: they have different meanings and must not use an ambiguous message.

Frequent errors are choosing a universal matcher without knowing the types, using machine-incompatible commands, ignoring the remote context, and putting prompt content in the banner. A well-documented personal control can remain small without becoming a plugin. For wider interface functions, Mods by Claude describes a different path.

What changes when multiple sessions are open?

An identical message from multiple sessions can make it difficult to figure out where to return. You can choose a short project label, defined locally and lacking confidential information. The label must serve to identify the window, without reporting the prompt or customer data.

Test the case with two test sessions, verifying which one produces the warning. If the system groups the banners, the delivery can be correct but not distinguishable. Do not solve this ambiguity by indiscriminately increasing the text: keep a clear name and read the detail in the session.

How to bring notification into the work process?

Define the message, event, recipient computer, and test procedure. It also retains expected behavior when the desktop is not available: a missing notification should not be mistaken for an unrequested session. The authoritative place for the decision remains the conversation of Claude Code.

For an organization that uses AI tools in different processes, one AI Consulting can clarify which moments really require human attention and which controls must produce evidence. A local notification works well when recalling a concrete decision, with little text and a precise meaning.

The configuration should be maintained when changing clients, operating system, or how to run the session. Try again the command and path of the hook after these changes; do not assume that a banner seen months before certifies the current environment.