claude-code-notify

Cross-platform desktop notifications for Claude Code. Get notified when Claude Code needs your attention — permission approval, task completion, idle prompts, and more.

Works as a Claude Code plugin (zero config) or as a CLI setup tool.

Platforms

Platform	Method
Windows	Toast notification (slides in from right)
macOS	Native notification center
Linux	notify-send (libnotify)
WSL	Windows toast via PowerShell

Notifications are silent by default. Use --sound to enable sound. Use --name to give your Claude a name.

Quick Start

npx @landienzla/claude-code-notify setup

Done. Restart Claude Code and you'll get desktop notifications.

Installation

Option 1: CLI Setup

npx @landienzla/claude-code-notify setup

This installs the notification script to ~/.claude/scripts/ and adds a Notification hook to ~/.claude/settings.json. Your existing settings are preserved.

Option 2: Plugin Mode

Install globally:

npm install -g @landienzla/claude-code-notify
claude --plugin-dir $(npm root -g)/@landienzla/claude-code-notify

Or per-project:

npm install @landienzla/claude-code-notify
claude --plugin-dir ./node_modules/@landienzla/claude-code-notify

Plugin mode requires no changes to your settings.json — the hook is loaded automatically via the plugin system.

CLI Commands

Command	Description
claude-code-notify setup	Install notification hook (silent)
claude-code-notify setup --sound	Install with sound enabled
claude-code-notify setup --name "Jarvis"	Install with a custom name
claude-code-notify dry-run	Preview what setup will change (no writes)
claude-code-notify test	Send a test notification
claude-code-notify uninstall	Remove notification hook and script
claude-code-notify help	Show usage info

Options can be combined: claude-code-notify setup --sound --name "Jarvis"

Run dry-run first to see exactly what files will be created/modified before committing.

How It Works

Claude Code fires a Notification hook whenever it needs your attention. This package provides a handler that:

1. Reads the notification context (JSON via stdin)
2. Extracts the message (e.g. "Waiting for permission to edit file.py")
3. Detects your OS
4. Sends a native desktop notification with the contextual message

Notification Events

The hook fires on all notification types:

• Permission prompts — Claude needs approval to run a tool
• Idle prompts — Claude is done and waiting for input
• Auth events — Authentication completed
• Elicitation dialogs — Claude is asking a question

Requirements

• Node.js — already installed if you're using npm
• Linux: libnotify-bin for notify-send

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

• macOS: Your terminal app may need notification permission in System Settings > Notifications
• Windows/WSL: PowerShell (included with Windows)

Uninstall

CLI mode:

npx @landienzla/claude-code-notify uninstall

Plugin mode: Remove the --plugin-dir flag from your Claude Code command.

Troubleshooting

Notifications not appearing on Windows/WSL:

• Ensure Focus Assist / Do Not Disturb is off
• Check Windows Settings > System > Notifications

Notifications not appearing on macOS:

• Go to System Settings > Notifications > [Your Terminal App] > Allow Notifications

Notifications not appearing on Linux:

• Install libnotify-bin (see Requirements)
• Ensure a notification daemon is running (e.g. dunst, mako, GNOME/KDE built-in)

License

MIT