Get a phone notification when Cursor's agent finishes

Updated October 17, 2026

Start a long agent task in Cursor and walk away. A stop hook sends a NextMsg push when the agent finishes or hits an error. If you'd rather the agent decide what's worth telling you, add the @nextmsg/mcp server and it gets a notify_human tool.

First, install the NextMsg app and copy your send key from Settings.

Option 1: a stop hook

Cursor runs hooks from hooks.json. Apps opened from the Dock don't see your shell profile, so keep the key in a small file:

mkdir -p ~/.cursor/hooks
echo 'NEXTMSG_KEY=nextmsg_live_YOUR_KEY' > ~/.cursor/hooks/nextmsg.env
chmod 600 ~/.cursor/hooks/nextmsg.env

Save this as ~/.cursor/hooks/nextmsg.sh and make it executable (chmod +x):

#!/bin/sh
# Cursor stop hook: sends a push when the agent finishes or fails.
. "$HOME/.cursor/hooks/nextmsg.env"
status=$(tr -d '\n' | sed -n 's/.*"status" *: *"\([a-z]*\)".*/\1/p')
case "$status" in
  completed) msg="✅ Cursor agent finished" ;;
  error)     msg="❌ Cursor agent stopped with an error" ;;
  *)         echo '{}'; exit 0 ;;  # aborted: you stopped it yourself
esac
curl -fsS --data-binary "$msg" "https://api.nextmsg.app/p/$NEXTMSG_KEY?channel=cursor" >/dev/null
echo '{}'

Then register it in ~/.cursor/hooks.json:

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

User hooks run from ~/.cursor/, so the relative path works. For a single project, put the files in .cursor/ in the repository and use .cursor/hooks/nextmsg.sh as the command. Keep nextmsg.env out of git.

Option 2: the MCP server

The @nextmsg/mcp server gives the agent a notify_human tool. It is open source: source on GitHub, package on npm.

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "nextmsg": {
      "command": "npx",
      "args": ["-y", "@nextmsg/mcp"],
      "env": { "NEXTMSG_KEY": "nextmsg_live_YOUR_KEY" }
    }
  }
}

The agent can now call notify_human(message, channel?). The key stays in the configuration and never enters the conversation. To make it a habit, add a line to your Cursor rules:

When you finish a task that took more than a few minutes, or you are blocked
and need my input, call notify_human with a one-line summary.

Which one to use

  • Hook: fires every time, with a fixed message. Good for "tell me whenever it stops".
  • MCP server: the agent writes the message ("Refactor done, 3 tests still failing") and only sends when it matters.

Both work together. The same setup works for Claude Code; see the Claude Code guide.

More guides