How to get notified when the Cursor agent finishes

Cursor's built-in completion sound and notifications

Cursor has two settings of its own, both in the app's Settings:

• A sound. Version 0.48 added a beta option to play a sound when a chat is ready for review. The 0.48 changelog gave the path as Settings → Features → Chat → Play sound on finish. Cursor's settings have changed since, so if you don't find it there, search the settings for sound.
• An OS notification. The 1.5 changelog says: "Get native OS notifications when an agent run finishes or when input is required." The example it gives is approving a command that is not allowlisted. It says to enable them from Settings, without naming the setting.

Both happen on the computer running Cursor and use Cursor's fixed wording. Neither reaches your phone, Slack or a second machine, and you can't change the text, so for those you need a hook (next sections). They are still the cheapest answer to "ding when it's done": try them first.

The Cursor CLI (cursor-agent) is separate. Its CLI changelog lists desktop notifications from April 2026 for a finished turn and for the agent being blocked on approvals, questions or sudo, in iTerm2, Ghostty, Warp, Kitty and Terminal.app. It doesn't say how to turn them on.

Cursor hooks by hand: the stop hook in hooks.json

Cursor hooks run a command of yours at points in the agent loop. Put them in ~/.cursor/hooks.json for every project (%USERPROFILE%\.cursor\hooks.json on Windows) or in .cursor/hooks.json inside one project. Cursor runs the matching hooks from every file and reloads the files when they change. This is the shape of the file. The command can be any shell string or script; the next section has working ones:

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": "./hooks/notify.sh"
      }
    ]
  }
}

What Cursor's hooks docs say about it:

• version is 1. Each key under hooks is an event name holding a list of entries. An entry needs command; timeout (seconds), matcher and failClosed are optional.
• stop fires when the agent loop ends. It gets JSON on stdin with status (completed, aborted or error) and loop_count, plus the fields every hook gets, among them conversation_id, generation_id, hook_event_name and workspace_roots.
• Exit code 0 means success, 2 blocks the action, and any other code is a failure that lets the agent carry on. A notification hook that fails therefore fails silently.
• A stop hook can print {"followup_message": "..."}, and Cursor sends that as the next message, up to loop_limit times (5 by default). A notification hook should print nothing or {}; a followup_message field would be sent as the next prompt.
• For user hooks, relative command paths resolve from ~/.cursor/, so ./hooks/notify.sh means ~/.cursor/hooks/notify.sh. Project hooks run from the project root.
• To debug, open the Hooks tab under Customize or the Hooks output channel. If a new hook still doesn't load, restart Cursor.
• User-level hooks in ~/.cursor/hooks.json are not available in Cursor's cloud agents, so a stop hook there (or npx anotifier@latest setup) sends nothing for a cloud run; those agents run a project's .cursor/hooks.json (and, on Enterprise plans, team and enterprise-managed hooks), on Cursor's machine rather than yours. Hooks don't run during a cloud agent's early read-only turns.

Cursor's documented events cover prompts, tool and shell calls, file edits, subagents and sessions, but none for "waiting for your approval". For that, Cursor's own OS notification above is the option.

A stop hook for macOS, Linux and Windows

Each hooks.json below shows a banner with a fixed message and ignores the event JSON. Linux (needs notify-send, from libnotify):

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": "notify-send \"Cursor\" \"Agent finished\""
      }
    ]
  }
}

macOS:

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": "osascript -e 'display notification \"Agent finished\" with title \"Cursor\"'"
      }
    ]
  }
}

Windows. Cursor's docs don't say which shell runs a hook command, so call PowerShell explicitly and use an absolute path with forward slashes. Save the toast script from the Codex guide (it takes a title and a message, and needs no module) as C:/Users/you/.cursor/win-toast.ps1, then:

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"C:/Users/you/.cursor/win-toast.ps1\" -Title Cursor -Message \"Agent finished\""
      }
    ]
  }
}

To put the status and project name in the message, read the event JSON in a script. This one needs jq; save it as ~/.cursor/hooks/notify.sh, run chmod +x on it, and point the hook's command at ./hooks/notify.sh as in the first example:

#!/bin/bash
input=$(cat)
status=$(echo "$input" | jq -r '.status')
project=$(basename "$(echo "$input" | jq -r '.workspace_roots[0]')")
notify-send "Cursor · $project" "Agent $status"

On macOS swap the last line for osascript -e "display notification \"Agent $status\" with title \"Cursor · $project\"". workspace_roots is the list of folders open in the window, so [0] is the first. Test it before trusting it: echo '{"status":"completed","loop_count":0,"workspace_roots":["/home/you/my-app"]}' | ~/.cursor/hooks/notify.sh.

anotifier setup for Cursor

npx anotifier@latest setup

Setup wires Cursor when a ~/.cursor folder exists. It copies hooks.json to ~/.anotifier/backups/, sets version to 1, and adds one entry under stop that runs anotifier's notify.mjs with --source cursor --event stop. Your other hooks stay; running setup again replaces anotifier's own entry instead of adding a second. Cursor reloads the file by itself.

What you get, and what you don't:

• One alert per finished run, titled Cursor and saying Task complete, as a toast, a phone push and a webhook message (whichever you enabled). A second stop within 1.5 seconds is dropped, because Cursor can fire the hook twice in quick succession.
• No project name. Cursor's docs list workspace_roots in the hook input, but anotifier reads cwd and workspacePaths and not workspace_roots, so every Cursor alert looks the same. With several windows open, the hand-written script above is the way to name the project.
• No status. anotifier doesn't read status, so a run you stopped or one that ended in an error says Task complete too.
• No click-to-focus. The Windows toast jumps to a window by project folder, and a Cursor alert has none, so there is no click action.
• Only `stop`. There is no alert for "waiting for approval". Leave Cursor's own OS notification on for that.
• Not driven by a live Cursor. CI checks that setup writes and removes the hook correctly; it doesn't run a real Cursor agent end to end.

anotifier is free, open source (AGPL-3.0), has zero dependencies, and uninstalls cleanly with anotifier uninstall. Full reference in the docs.

More on the Cursor page, and what setup writes for every agent in Agent hooks explained.

Phone push (ntfy) and Slack when Cursor finishes

By hand, a hook can post to ntfy. Install the ntfy app, subscribe to a topic nobody could guess (anyone who knows a public topic name can read it), and use it here:

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": "curl -s -d \"Cursor agent finished\" ntfy.sh/your-secret-topic"
      }
    ]
  }
}

With anotifier, answer yes to the ntfy question during setup. It creates a random topic, you subscribe to it in the app, and anotifier test ntfy should buzz your phone. The push is titled Cursor with the body Task complete. The full walkthrough is in the phone push guide.

For Slack, create an incoming webhook and put it in ~/.anotifier/config.json. Every Cursor finish then posts one message to the channel:

{
  "webhook": {
    "enabled": true,
    "url": "https://hooks.slack.com/services/...",
    "format": "slack"
  }
}

See the Slack page for the webhook steps. Discord and Telegram use a different format; the Discord page has the webhook steps for a Discord channel.

Cursor notifications on Windows and WSL

• Windows. The user hooks file is %USERPROFILE%\.cursor\hooks.json. Run setup in PowerShell, not in WSL. Setup also checks for PowerShell 7 (pwsh) and installs the BurntToast module for your user, so a toast arrives with the Cursor icon and a Windows notification sound. If pwsh is missing it prints winget install --id Microsoft.PowerShell --source winget. anotifier test toast confirms the toast works.
• Hand-written hooks on Windows can't use notify-send. Use the PowerShell toast above, and if nothing appears check that Do not disturb (Focus Assist) is off.
• WSL. Setup only looks in the home folder of the shell it runs in. If you run Cursor on Windows, run setup in PowerShell on Windows. If you run Cursor's agent from inside WSL, run it inside WSL, where the toast goes out through Windows interop. Cursor's hooks docs don't say which side runs a hook when a window is connected to WSL, so check with a real run: if the alert doesn't arrive, run anotifier status on both sides to see which one has the hook.

Details for both are in Claude Code and Codex notifications on Windows and WSL and Windows toast from WSL. Cursor is a VS Code fork, and the VS Code page covers what changes when the agent runs inside the editor, including Remote-SSH and dev containers.

Cursor notification not showing? Fixes by symptom

The order of checks that works for any agent is in the troubleshooting guide.

Turn off Cursor notifications

Try it

One command wires Cursor and every other agent you have installed.

npx anotifier@latest setup

Other guides

Claude CodeCodex CLIGemini CLIClaude Code permissionsClaude Code soundsClaude Code usage limitsClaude Code auto-compactClaude Code hooks securityccnotifyCodex CLI soundsAntigravity CLIWindows & WSLmacOS & LinuxAgent hooksTroubleshootingntfy phone pushWSL Windows toast