desktop-notify

graysurf's avatarfrom graysurf

Send desktop notifications (macOS/Linux) with a project-title wrapper.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[Developer Tools]

When & Why to Use This Skill

The Desktop Notify skill enables Claude agents to send native system notifications on macOS and Linux, providing a bridge between background agent tasks and the user's desktop environment. It allows for real-time status updates, error alerts, and progress tracking with support for project-specific branding and multiple severity levels, significantly improving the developer experience during long-running automated workflows.

Use Cases

  • Long-Running Task Completion: Alert the user immediately when a time-consuming process, such as a large-scale data transformation or a full system build, is finished.
  • Error and Failure Monitoring: Surface critical runtime errors or failed test suites directly to the desktop, ensuring developers can react to issues without constantly checking the terminal.
  • Workflow Milestone Tracking: Send 'success' or 'info' notifications when an agent successfully completes specific stages of a complex multi-step coding or deployment task.
  • Multi-Project Context Awareness: Use the project-title wrapper to distinguish notifications coming from different repositories or workspaces, helping users manage multiple agent activities simultaneously.
namedesktop-notify
descriptionSend desktop notifications (macOS/Linux) with a project-title wrapper.

Desktop Notify

Contract

Prereqs:

  • bash available on PATH.
  • Notification backend:
    • macOS: terminal-notifier
    • Linux: notify-send

Inputs:

  • Message string (required) and --level info|success|warn|error.
  • Optional env: AGENT_KIT_DESKTOP_NOTIFY=0 to disable; PROJECT_PATH for project title derivation.

Outputs:

  • A desktop notification (best-effort); silent no-op when disabled or backend missing.

Exit codes:

  • 0: success or no-op
  • non-zero: invalid usage or unexpected script/runtime failure

Failure modes:

  • Backend not installed (script no-ops by default).
  • Notifications disabled via AGENT_KIT_DESKTOP_NOTIFY=0.

Use this skill when you need to surface a short status update to the user via a desktop notification.

Prefer using the project wrapper (auto title) to avoid repeating title rules:

$AGENT_KIT_HOME/skills/desktop-notify/scripts/project-notify.sh "your short message" --level success

If you need a custom title, call the notifier directly:

$AGENT_KIT_HOME/skills/desktop-notify/scripts/desktop-notify.sh \
  --title "custom title" \
  --message "your short message" \
  --level info

Behavior

  • macOS: uses terminal-notifier when installed.
  • Linux: uses notify-send (libnotify) when installed.
  • Missing backend: silent no-op by default.

Environment

  • AGENT_KIT_DESKTOP_NOTIFY=0: disable notifications (default: enabled)
  • AGENT_KIT_DESKTOP_NOTIFY_HINTS=1: print a one-line install hint when backend is missing (default: disabled)
  • PROJECT_PATH: used by skills/desktop-notify/scripts/project-notify.sh to derive the project title (fallback: git root, then $PWD)

Install hints

  • macOS: brew install terminal-notifier
  • Linux (Debian/Ubuntu): sudo apt-get install libnotify-bin
  • Linux (Fedora): sudo dnf install libnotify