Agent notifications on macOS and Linux

On macOS and Linux anotifier uses the notification tool the operating system already has: osascript on a Mac and notify-send on Linux. Nothing runs in the background, and on macOS nothing extra is installed. Here is what each backend shows, what it needs, and how to check that banners really arrive.

Rather skip the manual setup? One command wires every agent you have installed to desktop toasts, phone push, and Slack, Discord or Telegram:

$ npx anotifier@latest setup

Updated 2026-09-25 · also see the full docs

macOS: osascript and Notification Center

Each toast is an AppleScript display notification call with the title (my-app · Claude Code), the message, and a sound. There is no helper app to install, which also means no custom icon and no click action: macOS shows the banner under the app it attributes AppleScript notifications to, usually Script Editor or your terminal.

Sounds map to built-in macOS sounds: finished tasks (IM) play Glass and approvals or questions (Reminder) play Ping. Mail maps to Purr, SMS to Tink, and Alarm to Sosumi. You can also name any built-in sound directly:

{ "events": { "task_complete": { "toastSound": "Hero" } } }

No banners? Open System Settings > Notifications, find Script Editor (or your terminal app) and allow notifications. The entry only appears after a first notification has been sent, so run anotifier test toast once first.
anotifier doctor reads that permission and warns when the app is not allowed. macOS does not expose this officially, so doctor treats the reading as best-effort.
anotifier doctor --deep sends a marker notification and reads it back from Notification Center's database, waiting up to 15 seconds. If the database can't be read, grant your terminal Full Disk Access in System Settings > Privacy & Security.
A Focus mode can hide the banner while macOS still records it as delivered, and doctor cannot tell whether a Focus is on.

Linux: notify-send

On Linux each toast is a notify-send call with the agent's icon, the title, and the message. It needs a desktop session with a notification daemon (GNOME, KDE Plasma, and most desktops ship one) and the libnotify command-line tool:

sudo apt install libnotify-bin   # Debian, Ubuntu
sudo dnf install libnotify       # Fedora
sudo pacman -S libnotify         # Arch

Priority becomes urgency. Approvals and questions go out critical, which the notification spec says should stay on screen until you dismiss it; finished tasks go out low. Sound names are ignored on Linux.

On a server, or over SSH with no desktop session, notify-send has nowhere to deliver. The toast fails, the failure is logged to ~/.anotifier/errors.log as toast:linux, and ntfy, webhooks, and the bell still deliver. On remote machines, phone push is the channel to rely on.

anotifier doctor warns when notify-send is missing.
anotifier doctor --deep sends a low-urgency toast and reads it back from dunstctl history if you run dunst. Other notification daemons report dispatched-but-unverified.

Test it

anotifier test toast    # prints Toast sent or Toast failed
anotifier doctor --deep # send a marker and read it back

If the test works but real notifications don't, the hook is the problem, not the backend: see the troubleshooting guide.

macOS & Linux: common questions

Why don't macOS notifications show the anotifier or agent icon?

AppleScript banners always use the icon of the app macOS attributes them to, usually Script Editor or your terminal. anotifier puts the project and agent in the title instead: my-app · Claude Code.

Do I need terminal-notifier?

No. anotifier only uses osascript, which ships with macOS.

Does it work on Wayland?

Yes. notify-send talks to the notification daemon over D-Bus, which works the same under Wayland and X11.

Can a headless Linux box notify my phone?

Yes. Toasts need a desktop, but ntfy push and webhooks work anywhere with network access. Enable ntfy during setup and subscribe to the topic in the ntfy app.