---

name: notifications description: "Desktop notification system for Claude Code. Use when discussing notifications, toastify setup, or when troubleshooting missing notification dependencies." version: 1.0.0

Desktop Notifications for Claude Code

This plugin sends desktop notifications via toastify when Claude needs your attention, so you can switch to other tasks while Claude works.

Installing toastify

The plugin requires toastify, a cross-platform CLI built on notify-rust.

Linux (Cargo)

Copycargo install toastify

On Arch Linux, it's available in the AUR:

Copyparu -S toastify
# or: yay -S toastify

macOS

Copy# Install Rust if needed
brew install rust

cargo install toastify

Note: macOS support uses mac-notification-sys under the hood, which provides a subset of Linux features.

Windows

Copy# Install Rust from https://rustup.rs first, then:
cargo install toastify

Windows 10/11 notifications work via Windows Runtime. Earlier versions have limited support.

Verify Installation

Run the check script to verify toastify is installed:

Copy~/.claude/plugins/user-notify/scripts/check-toastify.sh

Or test directly:

Copytoastify send "Test" "Notification working"

When Notifications Fire

By default, notifications fire on:

The Stop event (every Claude response) is disabled by default to reduce noise.

Configuration

Configuration uses YAML frontmatter in markdown files. Settings cascade from global defaults to project-specific overrides.

Config Locations

Precedence (highest to lowest):

1. Project-local config
2. Global config
3. Built-in defaults

Config Format

Copy---
notify_on_stop: false      # Notify after every Claude response
notify_on_questions: true  # Notify when Claude asks questions
notify_on_permission: true # Notify on permission prompts
notify_on_idle: true       # Notify after 60s idle
urgency: normal            # low | normal | critical
timeout: 5000              # Auto-dismiss after ms (0 = no timeout)
---

Example: Global + Local Override

Set global defaults in ~/.claude/user-notify.local.md:

Copy---
notify_on_stop: false
notify_on_questions: true
timeout: 3000
---

Override for a specific project in $PROJECT/.claude/user-notify.local.md:

Copy---
notify_on_stop: true       # Enable stop notifications for this project
urgency: critical          # Make them persistent
---

The project inherits notify_on_questions: true and timeout: 3000 from global, but overrides notify_on_stop and urgency.

Urgency Levels

• low — Subtle notification, may not make a sound
• normal — Standard notification (default)
• critical — Persistent notification that stays until dismissed

Timeout

Set timeout: 0 to make notifications persist until you dismiss them manually. Otherwise, notifications auto-dismiss after the specified milliseconds.

Notification Content

Title Format

[HEADING branch@dirname] Event

The title includes context to identify which project/worktree needs attention:

Example Titles

Body

The notification body shows context-specific information when available:

• Questions: The actual question text (truncated to 120 chars)
• Permission: The permission request message
• Other events: Generic description

Troubleshooting

"toastify not found"

The hook outputs installation instructions when toastify is missing. Follow the platform-specific instructions above.

Notifications not appearing (Linux)

Ensure a notification daemon is running. Common options:

• dunst (lightweight, highly configurable)
• mako (Wayland)
• Desktop environment's built-in (GNOME, KDE, etc.)

Check D-Bus notification service:

Copydbus-send --print-reply --dest=org.freedesktop.Notifications \
  /org/freedesktop/Notifications org.freedesktop.Notifications.GetCapabilities

Notifications not appearing (macOS)

Check System Preferences > Notifications and ensure notifications are enabled for Terminal (or your terminal app).

Too many notifications

Edit .claude/user-notify.local.md and disable unwanted triggers. The notify_on_stop: false setting (default) prevents notifications after every response.