├── README.md └── notify-cursor.sh /README.md: -------------------------------------------------------------------------------- 1 | # Cursor Agent Notifier 2 | 3 | A macOS utility script that sends notifications when Cursor's AI agent tasks are completed. 4 | 5 | ## Overview 6 | 7 | 8 | 9 | https://github.com/user-attachments/assets/d19dfa49-e6ad-4d6c-86e8-824dac9f9596 10 | 11 | 12 | 13 | This Bash script monitors Cursor's activity and notifies you when AI agent tasks complete while you're working in other applications. When clicked, the notification brings Cursor back to the foreground, helping you maintain productivity during long-running AI tasks. 14 | 15 | ## Features 16 | 17 | - Sends clickable macOS notifications that bring Cursor to the foreground 18 | - Avoids notifications when Cursor is already in focus 19 | - Simple setup 20 | - Complements Cursor's built-in sound notification feature with visual notifications 21 | 22 | ## Why Use This Script? 23 | 24 | While Cursor now includes a built-in sound notification feature (as of March 2025), this script provides additional benefits: 25 | 26 | - **Visual notifications**: Get macOS system notifications instead of just audio alerts 27 | - **Application focus**: Click the notification to immediately bring Cursor to the foreground 28 | - **No sound required**: Works perfectly in quiet environments where sound notifications are disabled 29 | 30 | ## Requirements 31 | 32 | - macOS 33 | - [terminal-notifier](https://github.com/julienXX/terminal-notifier) - A command-line tool to send macOS notifications 34 | 35 | ## Installation 36 | 37 | 1. Install terminal-notifier: 38 | 39 | ```bash 40 | brew install terminal-notifier 41 | ``` 42 | 43 | 2. Download the script (choose a directory to store the script): 44 | 45 | ```bash 46 | curl -o ~/notify-cursor.sh https://raw.githubusercontent.com/hgbdev/cursor-agent-notifier/main/notify-cursor.sh 47 | ``` 48 | 49 | 3. Make the script executable: 50 | 51 | ```bash 52 | chmod +x ~/notify-cursor.sh 53 | ``` 54 | 55 | ## Usage 56 | 57 | ### Setting Up With Cursor 58 | 59 | Add the new rule globally: 60 | 61 | ```text 62 | Execute the Bash script located at /Users/YOUR_USERNAME/notify-cursor.sh when a task is completed. 63 | 64 | Ensure this script is the last one executed for every task. 65 | ``` 66 | 67 | **Important:** 68 | 69 | - Replace `/Users/YOUR_USERNAME/notify-cursor.sh` with the absolute path to where you saved the script 70 | - The second line is optional but recommended to ensure notifications for all completed tasks 71 | 72 | ### Verification 73 | 74 | To verify the script works correctly: 75 | 76 | 1. Ask Cursor to perform a task that takes some time 77 | 2. Switch to another application 78 | 3. You should receive a notification when Cursor completes the task 79 | 80 | ## Troubleshooting 81 | 82 | - **No notifications**: Ensure terminal-notifier is installed (`which terminal-notifier`) 83 | - **Permission denied**: Check execute permissions on the script (`chmod +x notify-cursor.sh`) 84 | - **Script not found**: Verify the path in your Cursor instructions matches where you saved the script 85 | - **Terminal-notifier not found**: Make sure it's installed and in your PATH 86 | 87 | ## Cursor's Built-in Sound Notification 88 | 89 | As of March 2025, Cursor includes a built-in sound notification feature that plays a sound when a chat is finished. You can enable this feature in Cursor by: 90 | 91 | 1. Open Cursor Settings 92 | 2. Navigate to Features → Chat → Play sound on finish 93 | 3. Toggle the feature on 94 | 95 | This script works independently from Cursor's sound notification feature - you can use either or both depending on your preferences. 96 | 97 | ## Windows Users 98 | 99 | This tool is currently only implemented for macOS. Windows users interested in similar functionality might want to check out [SnoreToast](https://github.com/KDE/snoretoast), a command-line tool for creating Windows Toast notifications. A Windows version of this utility could potentially be built using SnoreToast and PowerShell. 100 | 101 | ## 📌 Author's Note 102 | 103 | > *As of June 7, 2025 — I personally no longer use this, as Cursor’s native sound notifications now meet my needs. But this script remains a great option for anyone preferring visual alerts or working in quiet environments. Cheers!* 104 | -------------------------------------------------------------------------------- /notify-cursor.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Author: Julian Huynh 4 | 5 | # Check if terminal-notifier is installed 6 | if ! command -v terminal-notifier &> /dev/null; then 7 | echo "Error: terminal-notifier is not installed. Install it with 'brew install terminal-notifier'." 8 | exit 1 9 | fi 10 | 11 | # Get the name of the frontmost application 12 | FRONTMOST_APP=$(osascript -e 'tell application "System Events" to get name of first process whose frontmost is true' 2>/dev/null) 13 | 14 | # Check if the frontmost app is "Cursor" 15 | if [ "$FRONTMOST_APP" = "Cursor" ]; then 16 | echo "Cursor is already the frontmost app. No notification sent." 17 | exit 0 18 | fi 19 | 20 | # Get the bundle ID of the Cursor app, with error handling 21 | BUNDLE_ID=$(osascript -e 'id of app "Cursor"' 2>/dev/null) 22 | if [ -z "$BUNDLE_ID" ]; then 23 | echo "Error: Could not retrieve bundle ID for 'Cursor'. Is the app installed correctly?" 24 | exit 1 25 | fi 26 | 27 | # Send the notification with improved title and message 28 | terminal-notifier -title "Cursor Agent Task Completed" -message "Click to open Cursor" -activate "$BUNDLE_ID" 29 | 30 | # Optional: Check if the app opened (rudimentary check) 31 | sleep 2 32 | if ! ps aux | grep -i "[C]ursor" | grep -v "notify_cursor" > /dev/null; then 33 | echo "Warning: Cursor app might not have opened. Verify the bundle ID: $BUNDLE_ID" 34 | fi 35 | --------------------------------------------------------------------------------