Get notified when Claude Code finishes or needs you on a Mac.

Claude Code's built-in alert fires when Claude finishes a task or pauses for a permission prompt, and you appear to be away from the terminal. Whether that alert shows as a banner depends on the terminal app.

Claude Code has one setting for this, preferredNotifChannel. In Claude Code, type /config and open Local notifications. The default is auto. The other choices are terminal_bell, iterm2, iterm2_with_bell, kitty, ghostty and notifications_disabled.

The terminal bell is the short sound or flash a terminal makes when a program asks for attention. To use it in Terminal.app, Warp or VS Code, you can also add this line to a Claude Code settings file, such as ~/.claude/settings.json, inside its outer braces:

"preferredNotifChannel": "terminal_bell"

• iTerm2: open Settings > Profiles > Terminal, check Notification Center Alerts, click Filter Alerts and turn on Send escape sequence-generated alerts.
• Terminal.app: to make the bell easier to notice, open Settings > Profiles > Advanced and, under Bell, choose to badge the Dock icon or bounce it when Terminal is in the background. If you accepted Claude Code's first-run terminal setup, it turned Terminal's audible bell off; check Audible bell there if you want to hear it.
• Any terminal: the terminal app itself needs permission to post notifications in System Settings > Notifications.

Older posts tell you to run claude config set. That command no longer exists: use /config or edit the settings file.

A hook is a shell command that Claude Code runs at a set moment. You list hooks in a settings file. They work in every terminal, because the terminal plays no part in running them.

Anthropic's own "get notified" recipe uses the Notification event. That event tells you Claude has finished only through idle_prompt, about 60 seconds later, and only if you haven't typed since. For an alert the moment Claude stops, use Stop.

A turn that ends on an API error, such as a rate limit, fires StopFailure instead of Stop. Notification hooks can't block anything: they only run your command.

Each snippet below goes in ~/.claude/settings.json, which applies to all your projects. Each one was checked for valid JSON and shell syntax and needs no extra software.

A Mac banner when Claude finishes.

In ~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'on run argv' -e 'display notification (item 1 of argv) with title \"Claude Code\" sound name \"Glass\"' -e 'end run' \"Finished in ${PWD##*/}\""
          }
        ]
      }
    ]
  }
}

A Mac banner when Claude needs your OK.

In ~/.claude/settings.json

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|elicitation_dialog|elicitation_url_dialog",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'on run argv' -e 'display notification (item 1 of argv) with title \"Claude Code needs you\" sound name \"Ping\"' -e 'end run' \"Waiting for your OK in ${PWD##*/}\""
          }
        ]
      }
    ]
  }
}

Both banners name the folder the session runs in.

Let Script Editor show the banners.

On a Mac, osascript banners come from the built-in Script Editor app. Until Script Editor is allowed to post notifications, the command fails silently, and macOS won't ask you for permission.

1. In Terminal, run this once:

osascript -e 'display notification "test"'

2. Open System Settings > Notifications, find Script Editor and turn on Allow Notifications.

A sound instead of a banner.

In ~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" } ] }
    ],
    "Notification": [
      { "matcher": "permission_prompt", "hooks": [ { "type": "command", "command": "afplay /System/Library/Sounds/Ping.aiff" } ] }
    ]
  }
}

A spoken alert.

In ~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "say \"Claude has finished\"", "async": true } ] }
    ],
    "Notification": [
      { "matcher": "permission_prompt", "hooks": [ { "type": "command", "command": "say \"Claude needs your permission\"", "async": true } ] }
    ]
  }
}

"async": true lets Claude Code carry on while the Mac speaks.

For a banner for one event and a sound for the other, use the notify hook generator twice: pick one event and its alert style each time, then use its merge box to add both results to your file. It tells you which file each snippet goes in, and everything runs in your browser.

• Trust the folder. Claude Code holds back every hook, even those in ~/.claude/settings.json, until you accept the workspace trust dialog for that folder.
• See what is loaded. Type /hooks in Claude Code. It lists your hooks and the file each one comes from, but it can't add them. Claude Code normally picks up your edits on its own; if it doesn't, restart the session.
• Work Macs. An organization can allow only its own managed hooks. Then /hooks shows "Only hooks from managed settings run here", and personal hooks won't run.
• Two alerts at once. Hooks from every settings level add up, so an alert hook in a project file and a different alert hook in your user file both fire. The exact same hook in several files runs only once. Hooks also run alongside the built-in notification. If you get both, set Local notifications to notifications_disabled and keep the hook.
• Too many alerts. Stop fires after every turn, not only when a whole task is done.
• If you also use Cowork Island. Keep each of your hooks in its own entry, as in the snippets above, and outside ~/.perch/. The app treats only commands containing /.perch/ as its own, and it replaces whole entries, so a command placed inside its entry would be removed with it.

• Claude Code docs: Terminal configuration
• Claude Code docs: Hooks reference
• Claude Code docs: Hooks guide
• Claude Code docs: Settings reference
• Claude Code docs: Settings
• Claude Code changelog
• Terminal User Guide: Advanced settings
• Mac Automation Scripting Guide: Displaying notifications
• Cowork Island FAQ and install guide

Sources checked 18 October 2026. This guide is written by Cowork Island's maker. For corrections, email support@coworkisland.com or open an issue on GitHub.