Alert recipes
Claude Code notifications: copy-paste recipes for every computer
Updated November 17, 20268 min read
Claude Code notifications tell you when Claude has finished a task or is stuck waiting for your answer, so you can do something else while it works. Below is one ready recipe per system: a Mac pop-up, a Windows message box, a Linux alert, a push to your phone and a plain terminal bell. Each one is a small piece of settings text you paste into a file, taken from Anthropic's own docs as of November 2026.
Before you cook: where the recipes go
Almost every recipe on this page is a hook. A hook is a small command that Claude Code runs by itself at a set moment. You write hooks into a settings file called ~/.claude/settings.json. The ~ means your home folder, so on Windows that is usually C:\Users\yourname\.claude\settings.json. If the file does not exist yet, create it.
Two hook moments matter for alerts. The Notification hook fires when Claude is waiting for you, for example to approve a command. The Stop hook fires each time Claude finishes a reply, which makes it the one to use if you want Claude Code to notify you when done. If your settings file already has a hooks section, add the new event next to the ones you have. Do not paste a second hooks section, or one will be ignored.
Tip
After you save a recipe, type /hooks inside Claude Code. It opens a list of every hook it loaded. If yours is not there, the file has a typo, usually a missing comma or bracket.
Recipe 1: a Mac pop-up when Claude needs you
This uses osascript, a tool built into every Mac, to show a normal macOS notification in the corner of the screen. Paste it into ~/.claude/settings.json:
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}What you'll see: a grey banner in the top right that says "Claude Code needs your attention".
If nothing appears, macOS is blocking it quietly. The pop-up is sent through the Script Editor app, and Script Editor needs permission to show notifications. Run osascript -e 'display notification "test"' once in Terminal, then open System Settings > Notifications, find Script Editor and turn on Allow Notifications.
Want a sound instead of a banner? Swap the command for afplay /System/Library/Sounds/Glass.aiff. That plays the Glass sound from your Mac. Any sound file in that folder works, so you can pick one you like.
Recipe 2: a Windows message box via PowerShell
Windows has no one-word notify command, so Anthropic's docs use PowerShell (the command tool built into Windows) to open a small message box:
{
"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')\""
}
]
}
]
}
}What you'll see: a pop-up box titled "Claude Code" with an OK button.
One catch: this is a dialog box, so it can open behind your terminal window. If you hear nothing and see nothing, move the terminal aside before you decide it failed. Test the command by itself in PowerShell first. If you run Claude Code inside WSL (Linux running inside Windows), also check that typing powershell.exe works in your WSL terminal. More Windows setup tips are on our Claude Code on Windows page.
Recipe 3: a Linux desktop alert with notify-send
Most Linux desktops come with notify-send, which shows a normal desktop notification:
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
}
]
}
]
}
}What you'll see: a desktop notification bubble from your desktop (GNOME, KDE and so on).
If the command is not found, install the libnotify-bin package on Ubuntu or Debian. It will not work on a server with no screen, over plain SSH, or inside most containers, because there is no desktop there to show the bubble.
Recipe 4: push alerts on your phone
This one needs no hook. Claude Code can send a push to the Claude app on your phone while Remote Control is on. Remote Control links a session running on your computer to the Claude app, so you can also reply from your phone. This is the simplest Claude Code push notification setup. Per Anthropic's docs, Remote Control needs a claude.ai login on a Pro, Max, Ultra, Team or Enterprise plan. API keys don't work for it.
- Install the Claude app on iPhone or Android. Typing
/mobilein Claude Code shows a QR code that opens the right app store. - Sign in with the same account you use for Claude Code, and allow notifications when your phone asks.
- In Claude Code, run
/remote-control(or start withclaude --remote-control). - Run
/configand turn on Push when Claude decides, Push when actions required, or both.
What you'll see: a Claude notification on your phone when a long task finishes or Claude needs a decision. You can also ask for one in your prompt, for example "notify me when the tests finish".
Your computer has to stay on for this, because the work still runs there. If /config shows No mobile registered, open the Claude app on your phone once so it can refresh. Claude Code also skips the push while you are typing in the connected terminal, so test it by walking away.
Recipe 5: the terminal bell, for any terminal
Some terminals already get a Claude Code desktop notification with no setup. As of November 2026 those are Ghostty, Kitty and iTerm2 (iTerm2 needs its alert settings on). Apple Terminal gets at most a silent bell, and every other terminal, including Windows Terminal, Warp and the VS Code terminal, gets nothing. To make Claude Code ring the terminal bell everywhere, add this one line to your settings:
{
"preferredNotifChannel": "terminal_bell"
}What you'll see: your terminal's bell. Depending on the app that is a beep, a flashing tab, or a bouncing icon in the Mac Dock. In Apple Terminal, also turn on Audible bell under Settings > Profiles > Advanced, or you will hear nothing.
Running Claude Code inside tmux (a tool that splits one terminal into panes)? Add set -g allow-passthrough on to ~/.tmux.conf so alerts reach the outer window. Our Claude Code with tmux page has the full tmux setup.
Recipe 6: a sound when Claude is finished
The recipes above fire when Claude is waiting. To get a Claude Code sound when finished, put the same command under Stop instead. This Mac example plays a sound after every reply:
{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }
]
}
]
}
}What you'll see: nothing, but you hear the Glass sound each time Claude stops talking.
Stop fires after every single reply, which gets noisy in a back-and-forth chat. Two matchers on the Notification hook are calmer options. A matcher is a filter that says which kind of alert the hook reacts to:
permission_prompt: Claude wants you to approve something and has waited about six seconds.idle_prompt: Claude finished about 60 seconds ago and you have not typed since. Good as a gentle "come back" nudge.
Give these two different sounds and you can tell "needs a yes" from "all done" without looking. Hooks run next to the built-in alert, so you can use a hook and the bell together. For more on hooks in general, read our Claude Code hooks guide.
All six notification recipes compared
| Recipe | System | Fires when | Setup effort |
|---|---|---|---|
Mac pop-up (osascript) | macOS | Claude is waiting | Paste a hook, allow Script Editor alerts |
| Windows message box | Windows, WSL | Claude is waiting | Paste a hook |
Linux notify-send | Linux desktop | Claude is waiting | Paste a hook, maybe install libnotify |
| Phone push | iPhone, Android | Long task done or decision needed | Remote Control plus two /config switches |
| Terminal bell | Any terminal | Done or waiting | One settings line |
Stop hook sound | Any system | Every finished reply | Paste a hook |
For one session in one terminal, the bell is usually enough. If you walk away from your desk, the phone push is the only recipe that follows you. If you want to hear about approvals quickly, use a permission_prompt hook. It fires about six seconds after Claude starts waiting.
When the alert never arrives
- Check `/hooks` first. If the hook is missing, the JSON did not load. Look for a missing comma.
- Run the command on its own in your terminal. If it fails there, it will fail as a hook too.
- Check the system's notification settings. Your terminal app (or Script Editor on Mac) needs permission to show alerts.
- Focus mode or Do Not Disturb on Mac, Windows or your phone hides alerts silently.
- You were looking at the terminal. Claude Code only sends its own alert when you seem to be away, so test by switching to another app.
- Several sessions, one sound. Every session plays the same hook, so you hear a beep and still have to find which window it came from.
Built-in alerts for a whole grid of agents
That last problem is the one hooks cannot fix well. When four or eight agents run at once, one shared beep does not tell you who needs you. VibeCodingDeck is a desktop app for Windows 10/11 and Apple silicon Macs that runs up to 12 agents in a grid and has alerts built in, with nothing to paste:
- A live status light on every pane: working, idle, waiting or done.
- Three alert levels (red, amber and blue in the title bar), each with its own sound.
- One click jumps you to the agent that is waiting on you.
- A single alert when the whole fleet has finished, instead of a beep per reply.
- It works the same for Claude Code, Codex, Gemini CLI, Grok, GitHub Copilot, Qwen, Kimi and Antigravity.
If that sounds like your day, see how people run multiple Claude Code agents side by side, or check pricing.
Notification questions
How do I make Claude Code notify me when it's done?
+
Add a Stop hook to ~/.claude/settings.json that plays a sound or shows a pop-up. It runs every time Claude finishes a reply. For fewer alerts, use a Notification hook with the idle_prompt matcher instead.
Why don't I get any Claude Code notifications on Windows?
+
As of November 2026, Claude Code only sends its own desktop alert in Ghostty, Kitty and iTerm2. In Windows Terminal, set preferredNotifChannel to terminal_bell or add the PowerShell hook from Recipe 2.
Can Claude Code send notifications to my phone?
+
Yes, through Remote Control. Install the Claude app, sign in with the same account, run /remote-control, then turn on the push options in /config. Your computer has to stay on, because the session still runs there.
Sources
Run up to 12 AI coding agents in one window.
Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.
Get startedKeep reading
Hooks cookbook
Claude Code hooks cookbook: 8 recipes to paste into settings.json
Agent manager
Claude Code dashboard: the six things you need to see at a glance
Parallel agents
How to run multiple Claude Code agents at once: four ways, easiest last
Terminal multiplexers
Claude Code and tmux for beginners: panes, keys and Windows options
Windows install guide
Claude Code Windows install: choose your method, then get it running