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