# Cursor

> Get notified when a Cursor agent run completes, is aborted, or fails. A Cursor stop hook in hooks.json that sends to Slack, Telegram, SMS, or email.

Source: https://docs.alphorn.dev/ai-agents/cursor/

Cursor runs commands on agent events through [hooks](https://cursor.com/docs/agent/hooks). The `stop` hook fires when an agent run ends and reports whether it `completed`, was `aborted`, or hit an `error`.

Cursor has no hook event for "waiting for approval": hooks like `beforeShellExecution` decide whether a command is allowed, they do not signal that you are needed. Use `stop` to know when to come back.

## 1. Create the hook script

```bash title="~/.cursor/hooks/alphorn-notify.sh"
#!/usr/bin/env bash
# Forwards the Cursor stop hook to Alphorn.
jq -c '{
  title: ("Cursor - " + ((.workspace_roots[0] // "agent") | split("/") | last)),
  message: ("Agent run " + (.status // "finished")),
  priority: (if .status == "error" then 4 else 2 end),
  tags: ["ai-agent", "cursor", (if .status == "error" then "error" else "completed" end)]
}' | curl -fsS --max-time 5 -X POST https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT \
  -H "Authorization: Bearer $ALPHORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- > /dev/null
exit 0
```

```bash
chmod +x ~/.cursor/hooks/alphorn-notify.sh
```

The script prints nothing. Output from a `stop` hook is read by Cursor: a `followup_message` in it would be sent to the agent as your next message.

## 2. Register the hook

```json title="~/.cursor/hooks.json"
{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "./hooks/alphorn-notify.sh" }]
  }
}
```

User hooks run from `~/.cursor/`, so `./hooks/alphorn-notify.sh` points to the script above. To enable the hook for one project only, put the script and `hooks.json` in the project's `.cursor/` folder and use `"command": ".cursor/hooks/alphorn-notify.sh"` (project hooks run from the project root). `ALPHORN_API_KEY` must be set in the environment Cursor runs in.

## Event fields

| Field | Description |
|---|---|
| `status` | `completed`, `aborted`, or `error` |
| `loop_count` | Number of agent loop iterations |
| `workspace_roots` | Open workspace folders |
| `conversation_id` | Conversation the run belongs to |

See [AI Agent Notifications](/ai-agents) for routing conventions and an `AGENTS.md` snippet (Cursor reads `AGENTS.md`) that lets the agent send notifications on its own.