How to get a notification when Claude Code finishes or needs your input

Last updated 7 November 2026 · Last verified against the Claude Code and Codex docs on 31 October 2026

The short answer Add "preferredNotifChannel": "terminal_bell" to ~/.claude/settings.json and Claude Code rings the terminal bell when it finishes or waits on a permission prompt, once you appear to be away. Claude Code sends desktop notifications by default only in Ghostty, Kitty and iTerm2, and iTerm2 shows them only after you turn on its alert settings. For a sound, a desktop toast or a phone push in any terminal, add a Stop hook (every finished turn) and a Notification hook (permission prompts and idle reminders). Or let a light show it.

Or let a light show it

A sound needs you at the desk and listening, and a toast needs you looking at the screen. A light works from across the room, with headphones on, and adds no extra ping.

What it does: AC Bridge turns the smart lights and plugs you already own (Hue, LIFX, Govee, WiZ, Home Assistant and more) into a status light for Claude Code and the Codex CLI, with the hooks already wired (on Codex you approve them once in /hooks). In the example colours from our homepage, the lamp breathes blue while the agent works, flashes red when it needs permission and turns green when it has finished; you pick the colours, and give each project its own lamp or let one lamp follow several.
What it costs: One plan: a 7-day free trial with no card needed, then £2.99 a month if you add a card to keep going; without one the trial just ends and nothing is charged. Cancel any time from your account. It works with the Claude Code or Codex you already run, on Windows, macOS or Linux. There is no API key to buy.
What it collects: LAN devices are driven straight from your machine and their keys never leave it; your account, settings, device list, usage counts and session states sync through our servers. Your prompts, code and session transcripts are never collected. Privacy policy.
What it follows: On Claude Code, AC Bridge takes needs permission from the Notification hook's permission_prompt matcher; finished follows Stop. On Codex it follows PermissionRequest, so the light changes as soon as Codex asks. See the hook events AC Bridge uses for the full list, and our Codex notifications guide for Codex's own alerts.

Generated image: a desk lit red, an example colour, while a Claude Code session needs permission.

Try it on your own lights Start the 7-day free trial, or read the setup docs and the status light guide first.

Get a notification or sound when Claude Code is done

Stop fires at the end of every turn, whether or not you are at the keyboard. Pick the command for your system. Every hook event, with more examples, is in the Claude Code hooks guide.

macOS: a notification with osascript

~/.claude/settings.json

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Claude Code finished\" with title \"Claude Code\"'",
        "async": true
      }]
    }]
  }
}

osascript posts through Script Editor. If nothing appears, run osascript -e 'display notification "test"' once in Terminal, then allow notifications for Script Editor in System Settings, Notifications.

Linux

~/.claude/settings.json

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "notify-send 'Claude Code' 'Finished'",
        "async": true
      }]
    }]
  }
}

notify-send needs a desktop notification daemon, so it does nothing on a headless server or over plain SSH. On Debian and Ubuntu it comes from the libnotify-bin package.

Windows

~/.claude/settings.json

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"New-BurntToastNotification -Text 'Claude Code', 'Finished'\"",
        "async": true
      }]
    }]
  }
}

BurntToast is a PowerShell module that shows a real toast in the corner of the screen. Install it once from Windows PowerShell, the shell the hook starts, not PowerShell 7: Install-Module -Name BurntToast -Scope CurrentUser. The command adds -ExecutionPolicy Bypass because Windows' default execution policy blocks module scripts. The project is archived and no longer maintained, but its last release is still on the PowerShell Gallery. The official docs use a MessageBox instead, which opens a dialog that can land behind your terminal.

Play a sound when Claude Code finishes

On a Mac, the command afplay plays a system sound file, so a Stop hook can ring Glass every time Claude finishes a turn. Linux and Windows need their own sound command, or skip the hook and use the terminal bell.

~/.claude/settings.json

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "afplay /System/Library/Sounds/Glass.aiff",
        "async": true
      }]
    }]
  }
}

Too chatty? Stop fires on every turn, one-line answers included. The idle_prompt matcher on the Notification hook waits until you have been away for about a minute. Still too much? See It fires after every turn.

Claude Code notifications not working

Each fix links the GitHub issue behind it, with its state as of 31 October 2026. A closed issue means the thread is closed, not that every symptom is gone, so try the fix on your own version.

The gotcha Both Notification types, and the built-in bell and desktop alert that share their timing, fire in a terminal only when you appear to be away: stop typing and they come, keep typing and they wait. permission_prompt waits about six seconds. idle_prompt is not a "waiting for input" signal: it fires about 60 seconds after Claude finished responding, and only if you have not typed since. For a signal the moment it happens, use Stop for "done" and PermissionRequest for "needs permission".

What you see	Most likely cause	Go to
Nothing in the VS Code extension	A Claude Code older than 2.1.233, or the bell setting, which is reported to do nothing in the extension panel	In the VS Code extension
The alert comes a minute after Claude stopped	`idle_prompt`, working as designed	It arrives about a minute late
An alert after every single reply	A `Stop` hook, or a `Notification` hook with no matcher	It fires after every turn
"Waiting for input" when Claude is not waiting	A reported Windows issue (#58753)	On Windows it fires when Claude is not waiting
Silence inside tmux	tmux is not passing the notification on	Inside tmux
You want the alerts gone	The built-in alert and your hooks switch off in different places	Turning notifications off

In the VS Code extension

Until Claude Code 2.1.233 the Notification hook did not fire for permission prompts in the VS Code extension or in Claude Desktop. Reports ran from October 2025 (#8985, 67 reactions) to July 2026 (#79881), and both were closed as fixed in 2.1.233. The bell and desktop-alert setting, preferredNotifChannel, is reported to have no effect in the extension panel (#92830, open). A request for native toasts in the extension, #57230, is open too, with 57 reactions.

What to do, in order:

Update Claude Code to 2.1.233 or later.
For a sound or a toast, use a hook rather than the bell setting. A Stop hook is reported to fire in the extension panel (in the threads of #79881 and #92830), and a maintainer said on #13203 that PermissionRequest hooks work from extension version 2.1.30.
Or run claude in the VS Code integrated terminal instead of the panel. The bell and the hooks then work as they do in any terminal.