Notify

notify

Native desktop notifications for Claude Code. Get notified when Claude needs your attention or finishes work — only when you're not already looking at the terminal.

Features

• Claude icon on notifications (macOS, via terminal-notifier)
• Fallback to built-in osascript if terminal-notifier isn't installed
• Linux support via notify-send
• Smart focus detection (macOS): skips notifications when your terminal is focused
• Configurable reminder alerts (toggle the "waiting for input" notification)
• Configurable sounds, title, and focus detection toggle
• Zero mandatory dependencies — works out of the box, better with terminal-notifier

Installation

claude plugin add BlackshearDevCo/claude-code-notify

Setup

The plugin works immediately after installation with no setup required. For the best experience on macOS, install terminal-notifier:

brew install terminal-notifier

To run the full interactive setup (backend detection, sound selection, focus detection, reminders):

/notify:setup

Commands

Command	Description
/notify:setup	Full interactive setup — backend, sounds, focus detection, reminders
/notify:config	Change individual settings
/notify:test	Send a test notification
/notify:preview	Preview all available sounds by category

Configuration

Preferences are stored in ~/.claude/notify.json:

{
  "attention_sound": "Ping",
  "completed_sound": "Purr",
  "focus_detection": true,
  "reminder_enabled": true,
  "title": "Claude Code"
}

Field	Default	Description
attention_sound	"Ping"	Sound when Claude needs your attention
completed_sound	"Purr"	Sound when Claude finishes work
focus_detection	true	Skip notifications when terminal is focused (macOS)
reminder_enabled	true	Notify when Claude is waiting for your input
title	"Claude Code"	Notification title text

Available sounds (macOS)

Any system sound name works. Common choices: Ping, Purr, Glass, Hero, Submarine, Tink, Pop.

Notification backends

Platform	Backend	Icon	Sound	Focus detection
macOS + terminal-notifier	terminal-notifier	Claude icon	Yes	Yes
macOS (fallback)	osascript + afplay	Script Editor icon	Yes	Yes
Linux	notify-send	System default	No	No

Troubleshooting

macOS: No notification appears

• Check System Settings > Notifications for either "Claude" (terminal-notifier) or "Script Editor" (osascript fallback)
• If focus detection is on and your terminal is focused, notifications are intentionally skipped

macOS: Want the Claude icon?

Install terminal-notifier: brew install terminal-notifier

Linux: "notify-send: command not found"

Install libnotify:

• Debian/Ubuntu: sudo apt install libnotify-bin
• Fedora: sudo dnf install libnotify
• Arch: sudo pacman -S libnotify