cursor-agent-notify

macOS notifications when a Cursor or Claude Code agent run finishes (Stop / stop hook). Cancels are silent (no banner when the run did not complete successfully).

Requirements

• macOS
• Cursor and/or Claude Code with hook support
• Node.js 18+
• terminal-notifier (recommended): brew install terminal-notifier
  If it is missing, the installer tries brew install when Homebrew is available; otherwise notifications fall back to osascript.

Not supported: OpenAI Codex CLI and similar tools without a Stop/stop hook API.

Install

From any directory:

npx cursor-agent-notify

Or clone this repo and run:

node ./bin/install.js

The installer will:

1. Copy on-agent-stop.sh to ~/.cursor/hooks/ and/or ~/.claude/hooks/ when the matching config directory exists.
2. Merge hook JSON (it does not remove your existing hooks; it only adds or updates the cursor-agent-notify entry).
3. Create ~/.config/cursor-agent-notify/config.sh on first run (never overwrites an existing file).

Restart Cursor and/or Claude Code after installation.

Customize messages (English by default)

Edit:

~/.config/cursor-agent-notify/config.sh

• MESSAGES_WITH_QUERY — use the placeholder __QUERY__ where the last user question should appear.
• MESSAGES_WITHOUT_QUERY — used when no short query was detected.
• NOTIFICATION_TITLE — notification title.
• OPEN_URL — URL opened when you click the notification (default: Cursor Glass deeplink). Set to empty to disable.
• CURSOR_BUNDLE_ID / CURSOR_APP_ICON — only applied when Cursor is installed under /Applications/Cursor.app.

Uninstall

1. Remove the hook entry from ~/.cursor/hooks.json (stop → command ./hooks/on-agent-stop.sh) and delete ~/.cursor/hooks/on-agent-stop.sh if you no longer need it.
2. In ~/.claude/hooks/hooks.json, remove the Stop block whose description contains cursor-agent-notify, and delete ~/.claude/hooks/on-agent-stop.sh if desired.
3. Optionally remove ~/.config/cursor-agent-notify/.

npm publish

npm login
npm publish --access public

License

MIT